Feature Branches

Overview

• group-token : feat/ (see "Naming" section)
• branches from : development
• merges into: development

Description

Feature branches match any of the following use cases:

• adding a new feature
• updating a current feature
• removing a feature
• creating experiments that may or may not necessarily be added to the project

Naming

All feature branch names will begin with the group-token feat/ and be followed by an approved prefix and then either a short name describing the feature or a custom group-token.

Prefixes

All branch names should include a prefix to describe the purpose of the feature. Below is a list of approved prefixes.

• add- : identifies a feature branch that adds a feature
• updt- : identifies a feature branch that updates a feature. This is useful for features whose original feature branches were deleted, or have already been merged with the master branch.
• rmv- : identifies a feature branch that removes a feature.
• exp- : identifies a feature branch that experiments with creating a new feature without plans of implementation.

Suffix

If the feature branch would reference or pertain to an open issue, then you should reference said issue with the issue's correlating number.

For Example: issue #213 suggests adding a new button component setting, so my branch would be something like feat/add-button-setting-213.

This makes it easy to keep concise branch names and be able to repeat similar branch names that will still be distinguishable by checking the referenced issue.

Custom Group-Tokens

Using another group-token after feat/ indicates that this feature branch will include a group of other feature branches. The name of the custom group-token uses lower camel case and ends with a forward slash, e.g., featureName/.

If feat/ is followed by another group-token, then that group-token MUST be followed by a description of the feature. This means that a maximum of 2 group-tokens (one being feat/ and the other being the custom group-token) should be used within a single branch name.

Note: Failing to follow a custom group-token with a feature description will prevent you from creating branches of this type in the future. For example, if you create a branch named feat/add-eventsPage/, you will not be able to create another branch called feat/add-eventsPage/feed.

If a custom group-token is used, it may be helpful to create a local, master branch for that group token to centralize associated branches, i.e., feat/prefix-groupTokenName/master.

Naming Examples

Example 1: Adding a Module

Say we wanted to create a new module for displaying a single news item; this module will be used in multiple areas throughout our project. Due to its flexibility and lack of associated modules, it's fair to say that this won't necessarily belong with a group of other feature branches.

Therefore, we could name this branch feat/add-newsItem.

Example 2: Adding a New Template

Say we were planning on creating a completely new template used for displaying a directory of employees. There are quite a few elements that would be a part of this new feature: a list of employees without images, a list of employees with images, individual employee pages, etc. Due to the multiple sub-features belonging to this new feature, there are quite a few ways that the branches could be named.

Method 1: With a Custom Group-Token

This method is recommended if the implemented features are isolated from other feature branches. We could create the custom group-token, dir/ and use the following branch names:

• feat/add-dir/master : local, master branch used to centralize the various sub-features.
• feat/add-dir/listImage : branch used to implement the list of employees that uses images.
• feat/add-dir/listNoImage : branch used to implement the list of employees that does not use images.
• feat/add-dir/individual : branch used to implement the individual employee page.

Once each sub-feature is finished, they could be merged into the local, master branch. Then, from that master branch, they could be merged into the development branch.

Method 2: Without a Custom Group-Token

This method is recommended if the implemented features will be used in other feature branches. We could simply create branches that only describe the specific feature that is being implemented. The branch names could include:

• feat/add-dirListImages : branch used to implement the list of employees that use images.
• feat/add-dirListNoImages : branch used to implement the list of employees that does not use images.
• feat/add-dirIndividual : branch used to implement the individual employee page.

Once each sub-feature is finished, they could be merged into the development branch to be implemented with other features.

Implementation

Once a feature is finished, it can be merged into the development branch where it will eventually be included in a release.