OpenRAM/.github/workflows

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 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 to see what "versioned commit" means.

2. 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).

3. 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', and 'public/stable'.

4. When there is a push with new version to the 'public/stable' branch, deploy workflow runs. It deploys the PyPI package of OpenRAM and creates a new GitHub release on that repo.

Important Notes

1. Workflows understand that the latest commit is versioned with the following commit message syntax.

   Bump version: <any message>
   

   Automatically generated version commits have the following syntax:

   Bump version: a.b.c -> a.b.d
   

2. version workflow only increments the right-most version digit. Other digits 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.

3. 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 workflow or was manually generated with caution.

4. regress workflow doesn't run on the public repo.

5. deploy workflow only runs on branches named 'stable'.

6. version workflow is only triggered from branches named 'dev' if they pass regress workflow.

7. sync workflow only runs on the private repo.

8. sync_tag workflow only runs on the private repo.

9. Merging pull requests on the private repo should be safe in any case. They are treated the same as commit pushes.

Warning: regress workflow is currently disabled on the public repo manually. This was done because of a security risk on our private server. Enabling it on GitHub will run regress workflow on the public repo.

Flowchart

flowchart TD

start((Start));
privatedev[(PrivateRAM/dev)];
publicdev[(OpenRAM/dev)];
publicstable[(OpenRAM/stable)];
regressprivate{{regress}};
regresspublic{{regress}};
syncnover{{sync}};
synctag{{sync_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