Feature branches

Introduction

On a daily basis, a project usually has two main branches:

• master / main, which should reflect the production environment state or its next release.
  Only ready-to-go code, without any pending development, should be merged in here. Merging anything else in here is a no-go, as it might block the release of critical fixes or smaller features in between.
• staging, which should reflect the code shipped for review and QA.

Any PR should be made against the main branch, merged to staging for client review, and merged back to main once approved.

In some cases, this workflow is not enough and might reach its limits, making the delivery of a set of dependent features more complex.

Why

Some features might require massive code changes and multiple PRs to be delivered. This is also often then case when you want to work with your teammates on a same feature, split into multiple tasks. Those tasks are not always independent and might require code from one or multiple PRs from other tasks.

Instead of creating PRs one by one, and waiting for them to be merged before starting the next one (or rebase on multiple PRs), you can create a feature branch and merge your work progressively.

It also prevent from blocking the release of other features or bug fixes, as the feature branch is not merged to main until fully ready.

How

Init

First, we'll create a new reference for every PR related to our feature, which will be used to track the feature progress and performing the final merge in main once ready for production.

1. Create a feature branch from main:

   git checkout main
   git pull
   git checkout -b feature/my-feature
   

2. Create an empty commit, so that you can create a META PR against main:

   git commit --allow-empty -m "[META] Feature: <My Feature>"
   git push origin feature/my-feature
   

3. Compare and create the META PR on GitHub. You can keep it as a draft Pull Request, so that most expensive workflows are not triggered.

Develop

Then use the usual workflow for your PRs, but instead of starting from the main branch, start from your feature branch and select it as your PR target:

1. Merge in staging once ready to be reviewed by the client
2. Merge to the feature branch once approved.

Note

You can still use gh-elao to perform the merges.

You can also maintain a changelog entry in your META PR description on each merge, so that you can easily track the progress and copy it when delivering the feature.

Deliver

When the feature tasks are fulfilled and approved, you can merge the feature branch to main.

Note

You cannot merge it with gh-elao, so this should be performed manually or using the GitHub UI.

PR description snippet

You can add such a snippet in your GitHub Saved Replies to bootstrap your META PR description:

Feature branch pour […]. <!-- Add a description of the targeted feature here -->

## Disclaimer

> **Note**: Les PRs ciblent cette branche plutôt que `master` / `main` et sont merged une fois validées.
Permet d'avoir un tronc commun pour lot de fonctionnalités sans impacter la branche de production.

## Rebase

> **Warning**: En cas de rebase sur `master` / `main`, attention à utiliser l'option `--rebase-merges`

```
git fetch -avp
git switch [feature-branch]
git pull --rebase
git rebase --rebase-merges --keep-empty origin/[master|main]
git push --force origin HEAD
```

## Merge

Avant de merger cette PR sur `master` / `main`, idéalement la rebase dessus.
Puis, merge (sans `gh-elao`):

```
git fetch -avp
git switch [master|main]
git merge --no-ff [feature-branch]
git push origin HEAD
```

> **Note**: Vous pouvez aussi la merger directement via l'interface GitHub, avec l'option `Create a merge commit`.

## Changelog

> **TODO**: complete with `gh-elao changelog [master|main]`

---

Last update: December 20, 2024