Update workflow documentation

.github/workflows/README.md

@@ -1,7 +1,10 @@
 # How do the workflows work?
 
 1. When there is a push to the private repo's 'dev' branch (private/dev),
-`regress` workflow runs the regression tests.
+`regress` workflow runs the regression tests if the commit is not versioned.
+`sync` workflow runs and makes sure that the versioned commit has a tag if it is
+versioned. See [important notes](#important-notes) to see what "versioned
+commit" means.
 
 1. If `regress` workflow fails on 'private/dev', `sync` workflow gets triggered
 and it pushes the latest changes to the public repo's 'dev' branch (public/dev).
@@ -9,10 +12,11 @@ After this push, `regress` workflow will also run on 'public/dev'.
 
 1. If `regress` workflow successfully passes on 'private/dev', `version`
 workflow gets triggered. It creates a new version commit and tag, and pushes to
-'private/dev', 'public/dev', 'public/stable'.
+'private/dev', 'public/dev', and 'public/stable'.
 
 1. When there is a push with new version to the 'public/stable' branch, `deploy`
-workflow runs. It deploys the PyPI package of OpenRAM.
+workflow runs. It deploys the PyPI package of OpenRAM and creates a new GitHub
+release on that repo.
 
 1. If there is a pull request on either repo, `regress` workflow runs on that
 pull request.
@@ -28,21 +32,23 @@ workflow gets triggered. It creates a new version commit and tag, and pushes to
 
 ## Important Notes
 
-1. Workflows understand that the latest commit has a new version with the
-following commit message syntax.
+1. Workflows understand that the latest commit is versioned  with the following
+commit message syntax.
 
     ```
     Bump version: <any message>
     ```
 
-    Automatically generated version commit have the following syntax:
+    Automatically generated version commits have the following syntax:
 
     ```
     Bump version: a.b.c -> a.b.d
     ```
 
 1. `version` workflow only increments the right-most version digit. Other digits
-in the version number must be updated manually following the syntax above.
+in the version number must be updated manually, following the syntax above. Just
+following this syntax is enough for workflows to create a new version
+automatically. That means, you don't have to tag that commit manually.
 
 1. `regress` workflow doesn't run if the push has a new version. We assume that
 this commit was automatically generated after a previous commit passed `regress`
@@ -65,5 +71,52 @@ should be avoided since it won't update the private repo automatically. To
 prevent merging by mistake, the dev branch can be protected in the GitHub
 settings.
 
-1. Merging pull requests on the private repo should be safe in any case.
+1. Merging pull requests on the private repo should be safe in any case. They
+are treated the same as commit pushes.
+
+
+
+## Flowchart
+```mermaid
+flowchart TD
+
+start((Start));
+privatedev[(PrivateRAM/dev)];
+publicdev[(OpenRAM/dev)];
+publicstable[(OpenRAM/stable)];
+regressprivate{{regress}};
+regresspublic{{regress}};
+syncnover{{sync/no_version}};
+synctag{{sync/fix_tag}};
+deploy{{deploy}};
+versionprivate{{version}};
+versionpublic{{version}};
+
+privateif1(Is versioned?);
+privateif2(Has version tag?);
+privateif3(Did tests pass?);
+
+publicif1(Is versioned?);
+publicif2(Is versioned?);
+publicif3(Did tests pass?)
+
+start-- Push commit -->privatedev
+    privatedev-->privateif1
+    privateif1-- Yes -->privateif2
+        privateif2-- No -->synctag
+    privateif1-- No -->regressprivate
+        regressprivate-->privateif3
+            privateif3-- Yes -->versionprivate
+            privateif3-- No -->syncnover
+
+start-- Push commit / Merge PR -->publicdev
+publicdev-->publicif1
+    publicif1-- No -->regresspublic
+        regresspublic-->publicif3
+            publicif3-- Yes -->versionpublic
+
+start-- "Push commit (from workflows)" -->publicstable
+publicstable-->publicif2
+    publicif2-- Yes -->deploy
+```
 

.github/workflows/deploy.yml

@@ -4,6 +4,7 @@ on:
     branches:
       - stable
 jobs:
+  # This job upload the Python library to PyPI
   deploy_pip:
     if: ${{ startsWith(github.event.head_commit.message, 'Bump version:') }}
     runs-on: ubuntu-latest
@@ -24,6 +25,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
+  # This job creates a new GitHub release
   github_release:
     if: ${{ startsWith(github.event.head_commit.message, 'Bump version:') }}
     runs-on: ubuntu-latest

.github/workflows/regress.yml

@@ -7,7 +7,7 @@ on:
     branches-ignore:
       - stable
 jobs:
-  # All tests should be run from this job.
+  # All tests should be run from this job
   regression_test:
     # This job runs on pull requests or any push that doesn't have a new version
     if: ${{ github.event_name == 'pull_request' || startsWith(github.event.head_commit.message, 'Bump version:') == false }}