Skip to content

Developer Overview

For new developers, visit the CDMSBats Flow Chart to find any resources you may need to get started with development.

For cdmsbats development we use the git flow model and the fundamental tenet is that the develop branch should never be behind the master branch. The git flow model is a branching strategy that allows a wide array of development and bug fixes while keeping the master branch working and ready for deployment.

It is recommended to use the helper program git flow-avh to help you work correctly in the git-flow model. The helper program provides short-hand commands that help enforce this branching model; a cheatsheet outlining git flow commands is at https://danielkummer.github.io/git-flow-cheatsheet/.

Prerequisites

Developers working on cdmsbats will need to be proficient in the following git skills - even for someone not making releases:

  • The git flow model.
  • Making a branch, and understanding the difference between branching off master and branching off develop.
  • Merging upstream changes.
  • Resolving merge conflicts.
  • If you are working on files inside BatCommon or IOLibrary, you will need to be familiar with git submodules.

Developers of any code should commit all files necessary to recreate their work. If you are unsure how to commit the necessary files (or changes to files) within the existing repository, contact the repository maintainers or Amy Roberts to determine a solution. To find help with using git, please ask for help in the git-help slack channel. You may also refer to this introductory guide to git.

Contribution policy

Contributions to the code are strictly streamlined through GitLab merge request.

The most recent contribution policy/instructions for SuperCDMS developers is available in this page.

Developer Scenarios and Explanations

Developers should use one of the following workflows when working on cdmsbats:

  1. If you need to be in control of when your code is merged back to master, you should work in the git-flow “hotfix” model, and branch off master.

    • Commit frequently on your hotfix branch - whenever you’d be sorry to lose your work.
    • Merge master back to your hotfix branch at least weekly (following the new policy for merge requests in the last section) - or whenever you commit to your hotfix branch, whichever is most sustainable for you. It is your responsibility to manage merge conflicts between your branch and master. Merging upstream changes frequently will make it easier to release your code once it’s ready.
    • Your branch is prepared for release once your changes are ready and you have merged the most recent changes on master to your branch. You may request a maintainer release your code, or release your code yourself - provided you follow the guidelines for a hotfix release in the git-flow model.

  2. If your work can roll with the uncertain release schedule, you can work in the git-flow “feature” model, and branch off develop.

    • Commit frequently on your feature branch - whenever you’d be sorry to lose your work.
    • Merge develop back to your feature branch at least weekly (following the new policy for merge requests in the last section)- or whenever you commit to your feature branch, whichever is most sustainable for you. It is your responsibility to manage merge conflicts between your branch and develop. Merging upstream changes frequently will make it easier to release your code once it’s ready.
    • Your branch is prepared for release once your changes are ready and you have merged the most recent changes on develop to your branch. You may request a maintainer release your code, or release your code yourself - provided you follow the guidelines for a release in the git-flow model.

git-flow Utility

The helper program git flow-avh can assist developers working in the git-flow model. However, this tool is not universally convenient to use.

Consider using the git-flow utility when: * You are working in the git-flow “feature” model. * You are working in the git-flow “hot-fix” model and expect to quickly complete and release your work.

Do NOT use the git-flow utility when: * You are working in the git-flow “hot-fix” model and you expect your work to take some time. The git-flow tool assigns a release tag when you start your work - if that release tag gets used while you are doing your work, you’ll have extra fuss to get your tags correct.

git-flow Development Model

Whether or not you use the git-flow utility, you are expected to follow the git-flow development model.

Git flow commands for feature development

``` git flow init git flow feature start MYFEATURE git flow feature publish MYFEATURE git pull git merge develop git flow feature finish MYFEATURE