Skip to main content

GitHub Workflow

This guide shows you how to use our branching model and release strategy, combining Git Flow with the GitHub CLI.

Branching Model​

We follow the standard Git Flow model to ensure the stability of our production code, adapted for our monorepo structure.

BranchPurposeStability
mainProduction releases. Every commit is a tagged release.Ultra Stable
developNext release development. Integration branch.Stable
feature/*New features or UI changes. Branch off develop.Experimental
bugfix/*Bug fixes for the next development cycle.Experimental
release/*Preparation for a new production release.Final Polish
hotfix/*Critical bug fixes for the production version.Urgent
support/*Long-term support branches for older major releases.Stable

Git Flow CLI Configuration​

Our local repository is configured with the following prefixes and tag rules:

Branch name for production releases: main
Branch name for "next release" development: develop
Feature branch prefix: feature/
Bugfix branch prefix: bugfix/
Release branch prefix: release/
Hotfix branch prefix: hotfix/
Support branch prefix: support/
Version tag prefix: v

Tooling Requirements​

To follow this workflow efficiently, we recommend:

  1. Git Flow CLI (AVH Edition): Usually included in Git for Windows or available via gitflow package.
  2. GitHub CLI (gh): Used for Pull Requests, status monitoring, and official releases.

1. Starting a New Feature​

Always branch off from develop. See the Command Reference for the exact git flow command.

2. Collaborating and Proposing Changes​

Instead of merging locally, we use Pull Requests for code review and CI validation.

  1. Push your branch to the remote repository.
  2. Create a Pull Request targeting develop (refer to the Command Reference for the gh pr command).

3. Senior Merge Strategy (Squash & Merge)​

To keep the develop history clean and meaningful, we use Squash Merges. This combines all commits from a feature branch into a single, well-described commit in develop.

  • Action: Merge via GitHub UI or CLI using the squash method (see the Command Reference for the exact CLI command).

Release & Versioning Workflow (Changesets)​

We use Changesets combined with GitHub Actions to automate our versioning, changelog compilation, and release Pull Requests. Developers do not bump package versions manually in package.json files.

1. Generating a Changeset (Local)​

When your feature or bug fix is ready and before opening a Pull Request:

  1. Run the interactive changeset tool from the repository root (see the Command Reference).
  2. Select the package(s) that were modified using the spacebar.
  3. Choose the appropriate SemVer bump level (Major for breaking changes, Minor for new backwards-compatible features, or Patch for bug fixes).
  4. Provide a clear, technical description of the change (in English, conforming to our commit standards).
  5. A temporary markdown file will be created under the .changeset/ directory (e.g., .changeset/warm-dogs-run.md).
  6. Commit this markdown file alongside your code and push it with your feature branch.
Keep Changesets Small

Create one changeset per isolated change. If a feature branch has multiple independent fixes or additions, you can run pnpm version:changeset multiple times to generate separate notes for each.

2. Automated Versioning Pipeline (GitHub Actions)​

Our CI/CD workflow handles the version bumping automatically when code is integrated:

  1. Pull Request & Integration: Developers open a Pull Request targeting the develop branch.
  2. Merge to develop: Once approved and merged into develop, the Manage Version Bumps and Releases GitHub Action is triggered.
  3. Release PR Generation:
    • The workflow parses the .changeset/*.md files present in the branch.
    • It calculates the new versions, consumes (deletes) the temporary changeset markdown files, bumps the respective package.json files, and updates the local package changelogs.
    • It automatically commits these changes and creates (or updates) an open Pull Request on GitHub named chore(release): version packages targeting develop.

3. Finalizing the Release (Maintainers Only)​

To publish and finalize the release:

  1. Open the automated Pull Request chore(release): version packages in GitHub.
  2. Review the compiled version changes and changelogs.
  3. Merge the Pull Request into develop. Because the changeset files have already been consumed and deleted, merging this PR consolidates the bumped package versions in the repository.
No Manual Version Bumps

Never edit the "version" field in a package's package.json manually during a normal feature branch. Always rely on pnpm version:changeset and let the GitHub Action pipeline manage the releases.

Critical Fixes (Hotfixes)​

If a bug is found in production:

  1. Start and finish a hotfix branch.
  2. See the Command Reference for the exact git flow hotfix commands.
  3. Sync both main and develop.
  • No direct commits to main or develop: Always use feature branches and PRs.
  • No Force Pushes: Unless on your own isolated feature branch and required for a rebase.
  • No Dirty Merges: Avoid merging main back into feature/*. Always rebase onto develop if your feature branch becomes outdated.