Development/Tutorials/Git/Feature Development Workflow/Staging Phase Explained

 

Warning
This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project.

Staging is a critical part of the whole workflow. It is a limbo where branches ready to be merged back into origin lie. This phase, despite seeming to be identical to integration, serves for a completely different purpose, and it is designed to prevent features from being blocked by freezes and giving origin a predictable behavior, making it as stable as possible.

What is staging

Staging is a branch which lives into the integration repository. It is a 1:1 copy of origin/master, on the top of which branches accepted for staging are merged and subsequently merged back into master: anything contained in staging is meant to hit origin as soon as possible.

Staging is meant to be used by maintainers only: it is likely that staging will be force-pushed from time to time, and is generally not safe for anything besides its purpose. In short: if you are not a maintainer and you are tracking staging locally, you are asking for troubles without any reason.

Usually, staging history is rewritten the moment staging is merged back into master.

The staging workflow and lifecycle

The staging workflow is based on lifecycles. A staging branch has a consistent history only throughout a single lifecycle. An usual lifecycle lasts 1 week, however, this is strongly dependent on freeze policies of the project. During a feature freeze period, the staging period lasts the whole freeze, and staged changes are pushed when origin is re-opened for features.

The staging lifecycle is described by the picture below:

The usual staging period based on a single week has the following timeframe:

• Day 1: Staging is reset to origin/master and is ready for staging branches and changes
• Day 2-6: Staging is open for merging features and branches. Staging is NEVER merged or rebased onto origin/master.
• Day 7: Staging is closed. A maintainer rebases staging onto origin/master, and subsequently merges staging into origin/master

In this scenario, maintainers have 2 days of grace period for preparing staging for the next lifecycle

Differences between staging and integration

The main difference between integration and staging is the merge strategy: while integration has a consistent history, derived from subsequent merges of origin/master, staging is a short-term branch which is always rebased on top of origin/master. From this perspective, staging can be seen as a cleaned up version of integration, aimed to preserve a linear branch history when merging features into origin. As a general rule, integration is always merged, staging is always rebased.

In addition, integration might see features which we do not want to stage yet. This happens in one of these two scenarios:

• A branch which might cause regressions or a very big branch: In this case, we give a grace period of two weeks to the branch, so that outstanding problems can be fixed in integration before hitting origin.
• A branch which has the sole purpose of making another branch work: Supposing we have a branch my-feature, which simply implements a feature needed for a branch feature-implemented to work, we usually want to stage them together. In this case, when the chain of dependencies is completed, all relevant branches get staged.

As previously stated, staging is NOT a working branch, but only a place where maintainers can handle the staging phase.