Skip to content

git-workflow.md

Latest commit

 

History

History
75 lines (48 loc) · 3.86 KB

git-workflow.md

File metadata and controls

75 lines (48 loc) · 3.86 KB
Raw

Git and GitHub workflow

Tip

GitHub CLI helps a lot in this workflow, especially to view or check out the PRs of other contributors (gh pr list, gh pr checkout <n>, gh pr diff). Worth exploring.

Main branches

Almost every RERO+ repository follows the same two-branch model:

  1. The master branch (main in the most recent repositories) stays at the latest official release tag.
  2. The staging branch, which is the default branch, contains the work being done during a sprint, between two releases. When it is ready, a release is cut from it and master is fast-forwarded to that commit. Whether it is a minor or a patch depends on the presence or absence of new features — the release workflow decides on its own, from the commit messages.

Most PRs are based on the default branch, that is staging, except when a user story branch is used.

The translations branch

The five repositories plugged into Weblate — rero-ils, sonar, rero-ils-ui, sonar-ui, ng-core — also have a long-lived translations branch: a buffer equal to staging plus the translations not yet released. It is written only by the nightly extraction workflow and by Weblate, and is squash-merged into staging once per release. Never develop on it, and never edit a translation file by hand. See how translations work.

Deployment branches

The deployed applications and UI libraries have these. For rero-ils there are as many branches as servers, and each one is built as a Docker Hub image:

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.

The Python libraries have nothing of the sort: they are published to PyPI, and consumed as a dependency.

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-yyyymmdd. 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. See the release workflow.

From a contributor point of view

Each contributor has their own fork and opens a PR (pull request) using either the staging branch as its base, or a specific branch corresponding to a user story (US), such as US-<name>.

Note

Remote convention. In the team's clones, rero/<repo> is the upstream remote and origin is your personal fork. Check yours once with git remote -v; the commands below assume it.

Updating your branches

  1. Fetch the changes:
    • git fetch --all -p (fetch all the remotes and prune).
  2. Place yourself in the branch you want to update:
    • git switch <branch> (or git checkout <branch>).
  3. Update your branch:
    • git pull upstream <branch> or
    • git rebase upstream/<branch> or
    • git reset --hard upstream/<branch> (this overwrites all your local changes).

Very often you will need to rebase your working branch on staging, because staging moved between the moment you opened your PR and the moment it is merged:

git fetch upstream
git switch <your-working-branch>
git rebase upstream/staging

You may need to resolve conflicts.

See also