Skip to content

Epic feature branches

Jump to bottom
Marc Durdin edited this page May 5, 2025 · 5 revisions

Epic feature branches

An epic feature branch can be created for a multi-sprint effort on a targeted work item.

Warning

An epic feature branch should not be created without the approval of team lead / project manager.

Before creating the epic feature branch, a design phase should be completed. The design phase includes:

  1. a design document (Google Docs)
  2. one or more design discussions (e.g. Monday sprint design meeting) to iterate on the design document
  3. eventually a spec issue, which includes tracking sub-issues and checklists etc, and supercedes the design document (which may get messy over time). This spec should be edited in the development process to match the final outcome of the epic, as far as possible.

All of this should really take place before crafting any code (prototype and exploration aside).

The root epic feature branch, which should normally be based on master, should be named epic/<shortname>, where shortname is a fairly short but recognizable name, for example epic/gestures, epic/ldml. Sub-branches should use the normal conventional commits prefixes (fix, feat, etc).

We will open a PR in draft for the epic and keep it open until the epic is complete. This PR is a good place to add comments relating to the ongoing work. We will pick a suitable emoji for the epic and append it to the title of the epic branch host PR. Our FH Actions will append the emoji to any PRs that target the epic.

Epic feature branches are automatically protected on GitHub, and cannot be pushed to directly -- all changes will require a pull request targeting the epic branch. Do not create sub-epics.

Short notes on working with epics

  • Any PRs targeting the epic must be reviewed and approved before merge.
  • It is important that work that lands in it is treated as 'finished'.
  • It is acceptable to have TODO items in PRs targeting the epic. These TODO comments must be formatted according to the epic name; see below for details
  • Before merge of the epic branch itself, all TODO items should be resolved or promoted into issues for future work, but this way we avoid clogging up the issue list, especially at early stages. (Using the TODO-EPIC-NAME pattern in source code makes it easy to find them amongst other, older, TODO comments in the source)
  • The epic branch itself will receive only cursory review before merge into master -- it is assumed that the PRs landing in it will be fit for production (apart from aforementioned TODOs).
  • Once a sprint, we generate a PR that brings the epic branch up to date with master. This is an opportunity to make sure that any changes in the epic branch do not drift too far from work on the alpha tier. See below for details.

Marking code TODOs in epic branches

Generally, we discourage usage of // TODO style comments in code without a corresponding tracking issue. However, during development of an epic feature, this pattern can be very useful, and adding many tracking issues is just busywork. However, to prevent the comments from disappearing into the background noise, use the epic shortname to make them easy to find:

// TODO-GESTURES: fixup the thingummy

Before merging the epic root branch into master, a search should be done for any remaining TODO-SHORTNAME instances, and these should either be addressed, or turned into issues.

Keeping epic feature branches in sync with master

We need to make sure we regularly merge master into our epic feature branches, to prevent the branches from diverging too far and creating a very difficult merge in the future.

There are many ways we could do this. We have chosen to use pull requests, so that we can more easily track the changes and review the merges.

Note

This process has been automated in the management repository at github/epic-master-merge/mergeMasterIntoEpic.mjs. Use this in preference to doing this manually.

The basic process is, for example for branch epic/x in sprint A18S4:

# Bring both branches up to date
git switch epic/x
git pull -p
git switch master
git pull -p
# Create the PR branch
git switch -c chore/merge-master-to-epic-x-A18S4
# Open the PR, basing it on epic/x branch
hub pull-request -op -M A18S4 -b epic/x

We do this, once per sprint:

  • for each epic feature branch
  • in reverse, from beta to master during beta phase
  • for staging branches on website repositories
Clone this wiki locally