Other branches

In previous chapters we mention usage of the master branch (which represents current active development) and Stable Branches (where backports following the stable branch policy are posted). Under specific conditions, it is possible to set up other types of branches, and this chapter will detail them.

Feature branches

Some complex features or significant refactors may take a long time to develop to the point where they are ready for merging on the master branch. Maintaining those features as a series of patchsets can be very painful. To handle those exceptional cases, projects may create feature branches, so that iterating on this large feature can be done as commits in a temporary git branch.

Creating the Branch

Feature branches should be used infrequently, because they bypass regular CI testing and usually result in extra pain and effort when the work needs to be merged back into master.

New feature branches can be requested using the same mechanism as stable branch creation. Submit a patch to the releases repository with a new feature/feature-name branch defined. Set the location value to the repository and commit hash from which to create the feature branch:

---
branches:
  - name: feature/example-feature-work
    location:
      openstack/oslo.config: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39

For more details, refer to the openstack/releases README.rst file.

Naming the Branch

Feature branches are named using a “feature/” prefix. What goes after that prefix is left to the choice of the project, but should generally describe the feature that will be developed on the branch.

Maintenance teams

Unlike stable branches, feature branches are not managed by a separate team. They are directly managed by the core review team for the project, like the master branch is.

Bug Branches

Projects that follow the independent or intermediate release models, especially library projects, may find that they need to release bug fixes in the middle of a cycle. Normally this should happen from the master branch of the project, even if there are new features. Fixes for stable branches are also supported (see Stable Branches). However, occasionally there is a need to release a fix into the master testing environment without releasing the current master branch of a project, because there are other breaking changes that are not yet ready to be released. For these cases, a branch can be made from the previous release tag using the prefix “bug/”, and the fix can be released from that branch.

Creating the Branch

Bug branches should be used extremely infrequently, because they represent a mechanism for releasing versions out of the normal development stream. New bug branches will be created by the release team at the request of the project team, after evaluating the need for the branch. A branch should only be created if there are breaking changes on the master branch of the project that cannot be released.

Naming the Branch

Releases from bug branches must only include fixes, and no features, so they can be given SemVer patch release versions, incrementing only the third part of the version number. The branch must be created from a previous release point, and the first two parts of that release’s version number will be used as the branch name. After the branch is created, patch releases for that major/minor version of the library may only be created from that branch, and the next release from master must increment at least the minor version of the library.

Example branch names:

1.12.0 -> bug/1.12
2.4.1 -> bug/2.4

Appropriate Commits

Only critical fixes, for gate breaks or security issues, may be included in a bug branch. All patches to the bug branch must be treated as a backport, and merged into the master branch before the bug branch.

Maintenance teams

Unlike stable branches, bug branches are not managed by a separate team. They are managed by the core review team for the project, in conjunction with the release management team.

Driverfixes Branches

Some projects include drivers for external devices or other vendor supported plugins. It was found to be a common issue with these projects that once the stable branches reach Phase II or later, fixes for drivers are no longer accepted. This resulted in many vendors maintaining their own stable trees, with some fixes included in one vendor’s repo and other fixes in another’s repo.

In order to provided a common place for distributions to pull in driver fixes past what the normal stable policy allows, these projects can create a driverfixes branch.

Warning

There is explicitly no expectation that any driverfixes branches will be kept in a deployable state. They are solely intended as a central collection point for driver fixes only and will not be updated with security or other critical updates that will go to the normal stable/* branches

Creating the Branch

Driverfixes branches are typically created when a stable release transitions into Phase II support. It is at the discretion of the project team when, and whether, they want to create a driverfixes branch. The branch itself is created from the current head of the stable/* branch it is supporting.

Naming the Branch

The driverfixes branches should be named for the release they are branching from and the code they are targeting. For example, for driver fixes for the Ocata release, the branch should be named driverfixes/ocata, for Pike, driverfixes/pike, and so on.

Appropriate Commits

Only fixes for driver code can be included. No changes to any non-driver code should be allowed. All patches to the bug branch must be treated as a backport, and merged into the master branch before the bug branch.

Pep8 and unit tests should continue to pass for any change introduced.

Maintenance teams

Unlike stable branches, driverfixes branches are not managed by a separate team. They are managed by the core review team for the project.