|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.
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 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:
In this scenario, maintainers have 2 days of grace period for preparing staging for the next lifecycle
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:
As previously stated, staging is NOT a working branch, but only a place where maintainers can handle the staging phase.