=========== 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 :ref:`Design Documents`). #. Visit the appropriate repository website (e.g., `Release Repository `_). #. Create a fork of the repository (see :ref:`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 :ref:`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 :ref:`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 <./dev_guidelines.html>`_. | | .. _Design Documents: 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: Forks ===== .. container:: row m-0 p-0 .. container:: col-md-12 pl-0 pr-3 py-3 m-0 .. container:: card px-0 h-100 .. rst-class:: card-header-def h4 .. rubric:: Fork .. container:: card-body-def 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: 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: 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 :ref:`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 three-number versioning system. For example, 0.0.0 or 1.5.0. In this case, where: * First digit : major feature release * Second digit : minor feature release * Third digit : bug fix release | Referring to the section on :ref:`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. | | | | |