Development¶

MPAS code repositories are hosted on GitHub. The typical life cycle of a project is as follows:

Create a design document for the project (see Design Documents).
Visit the appropriate repository website (e.g., Release Repository).
Create a fork of the repository (see Forks).
Locally clone the newly created fork (e.g., git clone https://fork/url).
Create a branch within the fork for the new feature or bug fix (e.g., git checkout -b new_branch). See Branch Strategy for a description of the MPAS branching strategy.
Develop the branch (e.g., touch src/framework/work_complete.F && git commit -a).
Push the completed branch to the remote fork (e.g., git push -u origin new_branch).
Submit a pull request to merge the branch on the fork to the main repository (see Pull Requests).

Projects do not have to follow this example verbatim, but this provides a general overview of the process. Some details related to this life cycle are described in the following sections.

Code level requirements are described in Development Guidelines.

Design Documents¶

Design documents are recommended for projects that contribute significant changes to either a core or to MPAS, in general. They should clearly describe the justification for the project, and the changes and impacts of the project. Core maintainers reserve the right to deny a pull request that lacks a design document.

Refer to DDT Redesign and Implicit Vertical Mixing (MPAS-Ocean) for examples of previously-completed design documents.

Forks¶

Fork

A user-specific copy of another repository.

To be able to make a fork of a specific repository, a user must have “pull access” to that repository. Permissions on a fork remain the same as the original repository (e.g. pull teams still have pull access over the fork), with the exception that the user creating the fork gains elevated administrative permissions over the newly-created fork.

A fork can be thought of exactly like a branch, except it lives in a separate repository and contains its own private history. As forks remember where they came from, they can still be merged onto the repository from which they were created.

See the GitHub Fork Tutorial to learn how to create a fork from a repository.

The user who created a fork is able to delete the fork, without destroying the original repository.

Pull Requests¶

A pull request represents several things in our development process. At its basis, a pull request is a merge request. It describes a branch that a developer wishes to have merged onto some alternate branch or repository. In addition to a request for a merge, it fully describes the changes involved in the merge, along with allowing for a full review of the merge prior to the actual merge.

Other developers can review and comment on pull requests. A pull request will be assigned to the relevant core maintainer.

GitHub provides guides for creating a pull request, using a pull request, and merging a pull request. Please refer to these guides for more instructions on pull requests.

Branch Strategy¶

As a developer, most work will be completed in a branch. This branch can be one of several types of branches. See A Successful Git Branching Model for an overview of the current branching strategy.

The name of a branch should be descriptive and tell where the feature addition will be. For example, if the branch is intended to implement multiple blocks, the majority of its work would take place in framework. A good name for the branch would then be framework/multiple blocks.

Feature branches should only be created from the develop branch. This allows a cleaner work flow when planning releases. Any features that have been merged onto develop can be staged for release. This means if a user submits a pull request for a feature to be merged onto the MPAS-Dev version of develop, they are giving consent for it to be included in the next coordinated release.

Release Branches¶

One of the branch types that developers will see in the shared repository is a release branch. This release branch is used to prepare the code for a new release, and includes some guidelines.

As per the branch document listed in Branch Strategy, release branches should branch off of develop. Once they are complete, they are merged into both develop and master. After they are merged into master, that commit is tagged with a new version number, and then pushed into the MPAS-Release repository for a public release.

A feature branch can be thought of as a “feature freeze.” Once the release branch is created, no new features can make it into the next release. The only commits that can be appended to a release branch are clean-up and bug fix commits.

Anything merged into develop can be released at any point in time. The guidelines for the release process are as follows, however the flexibility of these guidelines is at the discretion of the group performing the release.

From any point in time, the earliest date that code can be targeted for the release branch is one month from the current date.
Once a release date is selected, it will be anounced to those on the MPAS Developers list to alert all core developers.
There is a minimum lag time of two weeks between the announcement of a release date, and the creation of a release branch. This allows developers time to complete any outstanding projects that are close to being complete, and that they would like to be included in the next release.
After the two weeks, a release branch can be created from the tip of the develop branch.
The first commit to a release branch should be an update to the version numbers.
The maximum time a release branch is allowed to exist is two weeks. After this time it is assumed all core maintainer groups have completed any efforts to prepare for the release. At this point, the release branch is complete.
The release branch is then merged into master and develop.
The commit on master is tagged with the new version number.
The master branch is then pushed to the MPAS-Release repository.

These guidelines lay out a minimum amount of time a release cycle should consume. However, the core group that intends to release should announce the targeted date of release as soon as they have one selected.

Version Numbers¶

MPAS has a two-number versioning system. For example, 0.0 or 1.5. In this case, the first digit refers to a coordinated release. The second digit refers to intermediate bug fixes.

Referring to the section on Branch Strategy, coordinated releases occur when a release branch is created off of the develop branch and merged back into develop and master. While an intermediate bug fix happens when a branch is created off of master and merged back into master and develop.

The minor version (second digit) of MPAS increments when a bug fix branch is merged into master. These merges never include feature additions to any of the cores or shared framework.

The major version (first digit) of MPAS increments when a release branch is merged into master. A release branch includes all of the features that were present on the develop branch when it was created. The release branch persists for some period of time to allow core developers to “clean up” any issues they have prior to release. After the grace period, the release branch is merged into master and develop and the major version of MPAS increments by 1, while the minor version is reset to 0.