¶ Git and GitHub workflow
github-cli may help you in this workflow, especially to view or test PRs of other contributors. You're encouraged to discover it's possibilities.
¶ Main branches
The main RERO ILS git repository has two main branches:
- The
masterbranch stays at the last official release tag. - The
stagingbranch (default branch) contains the work being done during a sprint, between two releases. When thestagingbranch is ready for a release, thestagingbranch is pushed intomaster.
When a release is ready or needed, depending on the presence or absence of new features, a minor or a patch is published.
Mostly, the PRs will be based on the default branch, that is the staging branch, except when a user story branch is used.
¶ Deployment branches
Basically, there's as many branches as servers. For each branch, there's an image on Docker Hub:
- for ils.test.rero.ch:
ils_test. - for ilsdev.test.rero.ch:
ils_dev. - for bib.test.rero.ch:
bib_test.
Each deployment branch is built as needed, especially the ils_dev branch that may contain all the commits that need to be tested. On these branches, force pushing is not an issue, as they aren't used for development.
For the production server, they are at least three branches, allowing to quickly revert to a precedent version: latest and two precedent tags.
- for bib.rero.ch:
bib-latest,bib-1.4.10,bib-1.4.9(for
example, here the latest being thev1.4.11), corresponding to three images
on Docker Hub.
¶ Critical bug fix
When a critical bug needs to be fixed as quick as possible, a branch is created from the last tag in production (usually the master branch), named <last-tag>-fix. This branch will contain the fix. Depending on the situation, then this commit will need to be added to the staging branch too.
¶ Publishing a release
When a less critical bug is fixed by a commit on the staging branch, a release is published, which could be a minor or a patch version.
When reaching the end of the current sprint, a release may be published. Depending on breaking changes, it may be a major or a minor version.
¶ From a contributor point of view
Each contributor has his or her own fork and opens a PR (pull request) using either the rero-ils/staging branch as its base, or a specific branch corresponding to a user story (US), such as rero-ils/US-<name>.
¶ Updating your branches
- Fetch the changes:
git fetch --all -p(fetch changes of all remotes and prune).
- Place yourself in the branch you want to update:
git checkout [branch name]orgit switch [branch name].
- Update your branch:
git pull [remote name] [branch name]orgit rebase [remote name]/[branch name]orgit reset --hard [remote name]/[branch name](this will overwrite all
your local changes).
Very often, you'll need to rebase your working branch on the staging branch, because the staging branch has moved just before your PR opening or merging:
git switch <your-working-branch-name>git rebase <main-rero-ils-remote-name>/dev
You may need to resolve conflicts.
¶ Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests and should not decrease test coverage.
- Your code is as clear as possible and sufficiently documented (comments, docstrings, ...).
- All tests on GitHub Actions should pass before merging.
¶ Commit message style
Your commit message should follow Invenio's style guide. Commit message is first and foremost about the content. You are communicating with fellow developers, so be clear and brief.
(Inspired by How to Write a Git Commit Message
- Separate subject from body with a blank line.
- Limit the subject line to 50 characters.
- Indicate the component followed by a short description.
- Do not end the subject line with a period.
- Use the imperative mood in the subject line.
- Wrap the body at 72 characters.
- Use the body to explain what and why vs. how, using bullet points.
For example:
component: summarize changes in 50 char or less
* More detailed explanatory text, if necessary. Formatted using
bullet points, preferably `*`. Wrapped to 72 characters.
* Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
* Data Migration Instructions: if your PR makes changes to the data model
or needs an action when updating an existing instance, include
migration instructions (e.g. needs item reindexing, needs update mapping).
It is even better if you can also include an Alembic script directly in
your PR.
* Use words like "Adds", "Fixes" or "Breaks" in the listed bullets to help
others understand what you did.
* If your commit closes or addresses an issue in the same project, you can
mention it in any of the bullets after the dot (closes #XXX). If it
addresses an issue from another project, mention the full issue URL
(Closes https://github.com/rero/rero-ils/issues/XXX).
Co-authored-by: John Doe <john.doe@example.com>
Git signature: The only signature we use is Co-authored-by (see above) to provide credit to co-authors. Previously we required a Signed-off-by signature, however this is no longer required.