GitHub‐related

Branches

• main: Production code that is live here. May only be ahead of dev by hotfix commits.
• dev: Latest development code. From here, continuous releases are merged into main. Staged environment available here.
• experimental: Experimental branch that is unstable. We force push to it to set its HEAD to commits we like to test. The respective staged environment is available here. To force push to any commit, checkout any other branch, find the relevant commit id, then do git branch -f experimental <commit-id>, followed by git push -f origin experimental.

Generally, we try to follow this workflow closely, but without a separate release branch. Furthermore, we try to incorporate semantic versioning, although this is not a high priority as users always use the latest version, so breaking changes are not a problem per se.

• Use a squash commit to merge feature branches into dev.
• Use a merge commit to merge dev into main. The latter is referred to as "release". The respective pull request (PR) is called Continuous Release <version number, e.g. 1.8.0>.

Webhooks

Upon pushing to main, dev or experimental, a webhook is sent out to the Mathi server where the redeploy script for the respective environment is started. The logs can be viewed in real-time in Dozzle.

CI/CD

We make extensive use of CI/CD via GitHub Actions, e.g. to run a linter, our test suite (Rails test and Cypress end-to-end tests). In order to not waste resources, tests are only executed in the pipeline if we request so. This is mainly the case in the final phases of a pull request. You are free and encouraged to always run the tests locally as well. Especially when changing things, it's nice to run a specific test to make sure it still works.

Further conventions

• Commit messages: We follow this guideline. In short: Write in imperative style. Start with upper-case letter. No . at the end of the header line. Example: Add feedback button. Wrap header in 50 characters and commit body in 72 characters. Separate commit body from commit header by one empty newline.
• Keep your PRs
  • cohesive / self-contained: One PR for one well-defined "thing", e.g. for one new feature (that isn't too broad and doesn't contain several "subfeatures", fixing one bug etc.
  • minimal: The reviewer will thank you. Also: huge PRs are more error-prone.
  • tidy : No unnecessary noise, e.g. only change relevant files, do not intersperse with code refactoring / formatting of unrelated code.
  • When letting somebody review your code, ask yourself: is this code really ready for the final review? Would I like to review this code?
  • Use the "meta" values, e.g. give your PRs a label, assign it to a person etc. This helps in finding it later on.
  • When reading your PR comment, the reviewer should know exactly what it is about, what's its scope and what it maybe even doesn't touch upon. You may even add a small section with points that you think deserve special attention when reviewing. If your PR does some small "off-topic" things, include them in a dedicated "Off-topic" section in the PR comment as well, just for the sake of completeness.
• Other sane Git conventions ;)
• Conventions may be adjusted but should be documented.

Submodules

When a submodule (in our case: pdfcomprezzor) was updated, we can add a commit on our side to reference the updated version as explained here. However, everybody working on MaMpf still has to then receive the update locally by executing:

git submodule update --init --recursive  # Execute once the module was already updated