ADAPT Branching and Versioning Policy

Created by EricS
Last updated: 2020-04-02 by Stuart Rhea

The following document was approved by the Technical Committee on July 20, 2017.

Semantic Versioning

ADAPT uses the Semantic Versioning 2.0.0, described at http://semver.org/spec/v2.0.0.html.

Branching

ADAPT uses the Git Flow versioning model as described at http://nvie.com/posts/a-successful-git-branching-model/.

States for the ‘develop’ branch

Pull requests to ADAPT (outside of emergency hotfixes) are submitted to the develop branch. The develop branch always represents work being included for the next release of ADAPT. The technical leaders decide what type of release (patch, minor, major) will be the next release for ADAPT. The next release’s type guides what pull requests will be merged and which will be delayed for future releases. (Learn more later)

How to submit changes

Pull requests for changes must be forked from the develop branch and submitted back to the develop branch. For example, if a contributor adding a new property to an existing class which is already in develop should do the following:

  1. Fork the repository from AgGateway/ADAPT if they already haven’t
  2. Make the change in the develop branch, commit and push to your forked repo.
  3. Make a pull request from the forked repo for the develop branch back to the develop branch on the original AgGateway/ADAPT repo.

Improvements to unmerged features

Pull requests which represent changes to a feature which hasn’t been merged into the develop must be branched from and submitted back to the submitter’s repository on the develop branch. For example, if user ‘alice’ adds a new property to a class which user ‘bob’ has submitted a pull request for but it hasn’t been merged into develop, ‘alice’ should do the following:

  1. ‘alice’ will fork the repository from ‘bob’ who created the feature (or fetch the develop branch on ‘bob’).
  2. ‘alice’ makes the change in the develop branch, commits and push to 'alice's forked repo.
  3. ‘alice’ makes a pull request from 'alice's repo for the develop branch back to ‘bob’s develop branch.
  4. ‘bob’ will decide whether to accept the changes to their feature.

Emergency bugfixes

Emergency bugfixes may be made only for the current release on master. Bugfixes will be submitted as  pull requests and, if appropriate, merged based on the bug fix process of Git Flow. Emergency Bugfixes are for very rare situations where a bug must be fixed immediately and develop is not ready for a release.

Evaluating pull requests on AgGateway/ADAPT

Technical team members and the general public are welcome to comment on pull requests and give suggestions.

Once a pull request is submitted for inclusion (normally that’s when a pull request is submitted), the technical team will evaluate that pull request at the next meeting of the technical team. They will use the following process:

  1. If there are continuous integration tests, those tests must pass on the pull request. Additionally, the pull request should meet the coding standards for ADAPT and be technically accurate. If not, a technical team member (or CI as appropriate) should notify the submitter and give them advice on how to improve their pull request for acceptance.
  2. Does the change make sense in the general design of ADAPT? If not, a member of the technical team will post a reply, notify the submitter and close the pull request. In this step, the technical team should consider the needs of the next few major releases of ADAPT. If it makes any sense for the pull request to be kept open, it should be and the submitter should be encouraged to participate in further ADAPT activities.
  3. Can the change be added in a patch release? If so, the change should be merged into develop immediately.
  4. Can the change be added in a minor release? If so, the change should be marked in the pull request comments as being appropriate for the next minor release and the submitter should be notified. If the type for the next release is a minor release, you can merge immediately.
  5. Can be the change be added in a major release? If so, follow the next section.

Major pull requests handling

Any elements which will be removed as part of this major version change must be marked as deprecated for one major version. This provides users with sufficient time to know about changes and fully prepare for the change.

Processing pull requests requiring a major version change should follow this process (after following the initial steps listed in "Evaluating pull requests on AgGateway/ADAPT":

  1. The change should be marked in the pull request comments as being appropriate for the next major release and the submitter should be notified. 
  2. The Technical Team should evaluate and document which types and type members which currently exist in ADAPT and will be removed based by the pull request upon removal.
  3. The Technical Team (or the submitter if requested), should submit another pull request to AgGateway/ADAPT which consists of marking the removed types and type members as deprecated. If this pull request passes the conditions in step 1 of "Evaluating pull requests on AgGateway/ADAPT", this pull request should be marked as being appropriate for the next major release. If the type for the next release is a major release, the pull request should be merged immediately.

Creating a new version

Changing the type for the next release

Develop represents the next version to be prepared for release. By default, the next version type is a patch release. The technical team will decide via majority vote whether to change the next release type to minor or major.  Once a decision has been made on what the next release type is, the technical team will notify the community in the following manner:

  1. The README.md on Github
  2. A subscription mechanism (DIscourse or wiki)
  3. Announcements section on adaptframework.org

The technical team will begin processing the pull requests which have been marked as being appropriate for this version state. For example, if next version type is a minor release, all minor pull requests will be processed for inclusion. If the pull requests are out of date, the submitter must fix them before merger.

Making a release branch

Release branch changes

Changes can only be submitted to the release branch for bug fixes. Those bugfixes must be merged into develop immediately after merger into a release branch A release branch can be open for a very short period (simply long enough to formally create the branch and finalize the release) or longer based upon the community testing required for the release.

Finalizing a release

The technical team will decide via majority vote when to finalize a release. Upon release finalization, the release branch will be merged  into master and the commit will be tagged with the version.  Merging and tagging should trigger the official NuGet.org package creation and posting. The release branch will be closed.

NuGet packages

Development packages have two subsets: develop branch and prerelease. Develop branch packages are automatically created no more frequently that once daily from the contents of the develop branch and are posted to NuGet with the postfix of "DATE-nightly" where date is in the 'YYYYMMDD' format. These packages provide very early testing for those who use ADAPT from NuGet.

Prerelease packages are automatically created no more frequently than once daily from the contents of a release branch. These versions are marked as prerelease and are posted to NuGet.org. This provides early testing for new versions.