This topic covers the workflow used within LabKey to facilitate collaboration between developers and testers on new features. Each feature is described and specified by a story or set of related stories. We use a branching workflow for all stories involving Git-hosted modules. This workflow isolates features until they are complete; avoiding undesired interactions between unrelated, in-development features. This also allows us to get test coverage of features earlier in the development process. In a nutshell the Feature Branch strategy LabKey uses is similar to this Atlassian Feature Branch Workflow, except that the branches created are less focused. Instead of each remotely shared branch being specific to a feature, ours are specific to a story, or set of related stories. Developers may wish to create sub-branches for individual features, but it is not required.

Feature Branch Workflow

When beginning work on a feature or bug fix, a developer will create a remote shared branch for development and verification. At one point, we might have the following projects in progress:

  • Info pane: Filter breakdown view
  • Issue 22222: Home page formatting is incorrect
  • Add Antigens and Analytes section to variable selector
  • Add User groups to variable selector
Work for those stories will be isolated into several feature branches:
  • fb_infopane_11111
  • fb_homepage_22222
  • fb_plots_33333 (includes work for antigens and user groups). These stories are independent parts of a single deliverable so we create branches for them as children of this branch (optional).
    • fb_plots_antigens_33333
    • fb_plots_groups_33333
Each feature branch will be prefixed with fb_, it should also include a short descriptive name and the spec ID for the story. TeamCity is configured to track these branches, build against them, and run relevant tests when code changes are pushed. However, TeamCity will NOT run any broad-scope nightly suites against them.

Feature branches can be based on develop, or on a release, snapshot, or other branch, depending on where in the development cycle the feature is added. We do our best to treat develop as a stable branch, meaning commits are not allowed on the branch until they are considered stable changes. In order to merge one of the feature branches into the develop branch the branch must have:

  1. All features complete
  2. All new tests complete
  3. All tests must be passing
  4. Manual acceptance testing must be completed
  5. No high priority bugs
  6. A code reviewed pull request
Once a feature branch is merged into develop the feature branch shall be deleted. If a bug is found after a merge the developer assigned will create a new feature branch, fix the bug, then, when stable, merge into develop.

If you have a top level branch that includes children branches for related stories, then the top level branch is the only branch that needs to complete manual and automated testing as well as bugfixes. You may complete new dev in the child feature branch and merge it into the top level feature branch, however the top level feature branch will not be merged until all bug fixing and testing is complete, so it's best to have that complete in the child feature branch. Make sure when merging a child feature branch into a top level feature branch that tests are run and a quick manual test pass is complete to ensure nothing was messed up during the merge.

More Info

See the Git Branching documentation for more information on naming schemes for other scenarios, including bug fixes and features targeting an existing release.

The Workflow in Practice

Create the Remote Feature Branch

After you have determined the branches you want and have coordinated with the Kanban team, you can run the following commands to create them (or create it through the GitHub web interface):

git checkout develop # Most features are based off of develop. 
git pull origin develop # make sure you create your branches off of the most up to date version of the base branch
git checkout -b <fb_featurebranch> # create the branch
git push --set-upstream origin <fb_featurebranch> # push the branch so it is a remote and can be shared with other developers
# The feature specification should indicate the name of the remote branch for the story.

Develop Features

Now that you have your branches you can start developing.

git checkout <fb_featurebranch> 
# do some work, make some commits…
git pull --rebase # Get the upstream changes from other people.
# Merge your changes with the upstream changes. Run some tests to verify.
git push # Push your changes so everyone can see them.

Ensure Stability

Eventually you'll complete all the features required for the story, you'll have written all the new tests required, and you'll fix all the bugs found during manual testing.

Once the story is ready to deliver, you will need to verify that it is ready to merge:

  • Merge upstream changes into the feature branch from develop
  • Confirm that module tests are passing for your feature branch on TeamCity. Some troubleshooting tips are available here.
  • Create a pull request
    • Assign code reviewer for product code
    • Assign code reviewer for test code
Once the feature branch has been code reviewed and any requested changes have been addressed it is your responsibility to merge the pull request and delete the feature branch. Notify any other collaborators to that branch so that they don't accidentally push more changes and recreate the branch. Any additional changes that were not included in the pull request merge should be treated as a separate bug fix and should be committed to a new branch off on develop.

Merge Feature Branches

There are a number of merge scenarios for feature branch development.

  • origin/fb_feature --> fb_feature
    • Update your local working feature branch
    • This merge should happen fairly frequently during feature development
    • This is the only time you should rebase.
  • origin/develop --> fb_feature
    • Update a feature branch to include upstream changes
    • Should be done periodically by the primary feature developer
    • Inform other feature developers so that they can pull the changes
    • May be done via pull request (PR) if you want a code review or other PR functionality
    • Use standard merge to avoid causing conflicts for other developers
  • fb_feature --> origin/develop
    • Merge a feature branch back to develop
    • The final step before marking a story complete on the Kanban board
    • The feature should be fully functional and fully tested (manual and automated)
    • Should be done via pull request
    • Use Squash and Merge, which is available via the pull-down button when doing the merge of the pull request in the GitHub UI.
    • Create a good commit message for the squash commit
Regardless of the scenario, you should always build and run tests before pushing.

A pull request requires approval from another developer with write permissions to the repository. For repositories that are developed by or in conjunction with external developers, that review can be done either by a LabKey or external developer.

Multiple Repositories

Some features and bug fixes require changes to code from multiple repositories.

  • The branch names must be the same across repositories so that TeamCity will know to match them up.
  • When it is time to create them, pull request titles should be identical across all of the repositories.
  • Merges should be done simultaneously for all repositories

Upgrades and Core Refactors

Major refactors and upgrades should be performed in a feature branch just as we do with other development.

As soon as these refactors are merged to develop, they should be merged into all feature branches.

Because of the far-reaching effects of such changes, extra care should be taken.

  • Before merging to develop, verify major refactors against more extensive suites (e.g. Dailys) than are automatically triggered by TeamCity
  • Communicate with feature branch developers so that they can merge from develop as soon as possible.

Installers

We do not automatically build installers against feature branches on TeamCity. You will need to build such installers locally or request that a developer create one for you. There is a special TeamCity project, Installer - Custom, that can be used to create an installer for single distribution against a feature branch.

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand allcollapse all