Skip to content

3.2. Contribution and Release Workflow

Jump to bottom
Mark Edward M. Gonzales edited this page May 20, 2024 · 28 revisions

This page discusses the workflows for contributing to RicePilaf and publishing a release.

Repository Branches

To understand the workflows, it is important to first gain familiarity with the repository branches. The figure below presents a graphical illustration of the workflow across the different branches:

Repository Branches
  • The blue branches are protected branches that cannot be deleted.
  • The red branches are special branches created to publish releases. They are deleted automatically once the pertinent release is published as part of the automated release workflow.
  • The yellow branches are short-lived branches that have to be deleted manually once their purposes are served.
  • The names of the blue and red branches are fixed. The yellow branches can be named differently, provided they do not conflict with the blue and red branches.
  • A solid arrow indicates that the action (push or pull) has to be performed manually by the user.
  • A dashed arrow indicates that the action (push or pull) is performed automatically as part of some automated workflow.
Click here to show/hide the description of each branch
Branch Description Remarks
main This branch stores the latest release Protected to prevent deletion
major-release This branch is created from dev to publish a major release Deleted automatically once the major release is published as part of the automated release workflow
minor-release This branch is created from dev to publish a minor release Deleted automatically once the minor release is published as part of the automated release workflow
hotfix This branch is created from main in case a patch is needed (the development of the patch happens here) Short-lived. Delete manually after patch is created and the completed patch is published
patch This branch is created from hotfix to publish a completed patch Deleted automatically once the patch is published as part of the automated release workflow
dev This serves as the integration branch for features under active development Protected to prevent deletion
feature-1, feature-2, etc. Each feature under active development resides in its own feature branch Short-lived. Delete manually after merging with dev or once feature development is completed

1️⃣ Contribution Workflow

  1. Create a feature branch from dev. Each feature under active development resides in its own feature branch.
  2. Before pushing to your feature branch, run your code through the formatter and linter specified here.
  3. Once feature development is completed (or, in the case of a complex feature, a significant portion is finished), create a pull request from your feature branch to dev. This will trigger the workflows for checking the syntax and code formatting and for vulnerability scanning via CodeQL.
  4. Wait for your pull request to be accepted. Please do not accept your own pull request.
  5. Delete your feature branch once feature development is completed.

2️⃣ Release Workflow

Publishing a Release

Let x.y.z be the version number. A major release bumps x. A minor release bumps y. A patch bumps z.

There are no strict rules as to what constitutes a major release, a minor release, or a patch. However, note that the data version is tied to the minor release version. For instance, all releases tagged as 0.1.x should run with the dataset tagged as 0.1.

The steps to publish a release are as follows:

  1. The automated release workflow is triggered by the creation of special branches:

    • For a major release: Create a remote branch named major-release from dev.
    • For a minor release: Create a remote branch named minor-release from dev .
    • For a patch: First, create a remote branch from main; for simplicity, we name this branch hotfix. The development of the patch happens in hotfix. Once the patch is completed, create a remote branch named patch from hotfix. The creation of patch triggers the automated release workflow. Finally, delete hotfix manually (patch is deleted automatically).

    ⚠️ Important: Make sure that you are in the right branch before creating the remote branch for a release (e.g., make sure that you are in the dev branch before creating major-release), especially since remote branches are, by default, created from main.

  2. Update the changelog of the release here.

  3. Update the wiki as needed.

  4. If you are publishing a minor or major release:

    • Update the link to the app dataset and the checksum on the Installation wiki page, as well as the link to the workflow dataset and the checksum on the Data Preparation wiki page.

    • We maintain older versions of the app and workflow datasets for compatibility with older release versions of RicePilaf. The links to the Google Drive folders storing these older dataset versions are on their respective wiki pages. Make sure that:

      • The app and workflow datasets accompanying a minor or major release are uploaded to these Google Drive folders.
      • The Google Sheets recording the checksums are updated accordingly.

Other Matters

a. Correcting Mistakes

To err is human — and it is admittedly quite easy to create the release branch from the wrong branch.

Click here to show/hide the steps for correcting mistakes related to publishing a release

  1. Stop all running workflows here.

  2. If a release has already been published, delete the release here.

  3. If an image has already been built, delete the image from the GitHub Container registry (app, deploy, and workflow).

  4. If a release tag has already been created, delete the release tag here.

⚠️ Important: Performing all these steps is crucial to fully delete the incorrect release and reset the release version counter.

b. Modifying the Template for the Release Notes

The template for the release notes can be edited by modifying the RELEASE_BODY variable in the release-on-push job defined in this workflow file.

c. Understanding the Automated Release Workflow

Click here to show/hide the steps performed as part of the automated release workflow

  1. Push the release branch to main (workflow file). This ensures that main always stores the latest release.

  2. Create a release, bumping the version number (workflow file).

  3. Delete the release branch (workflow file).

  4. Fetch the latest release, build the Docker images, and store them in the GitHub Container registry (workflow file). To shorten the build time, the Docker images for the app (local version), workflow (data preparation), and deployed version are built in parallel using a matrix strategy.

Clone this wiki locally