Skip to content

Commit

Permalink
Merge pull request #73 from LLNL/feature/zagaris2/update-release-proc…
Browse files Browse the repository at this point in the history 
…ess-instructions

Feature/zagaris2/update release process instructions
  • Loading branch information
@gzagaris
gzagaris committed Aug 8, 2019
2 parents 5ce2197 + e6fda17 commit 807e93b
Showing 1 changed file with 105 additions and 69 deletions.
174 changes: 105 additions & 69 deletions src/docs/sphinx/dev_guide/release.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@
Axom Release Process
*******************************************

The Axom team decides as a group when the code is ready for a release.
The Axom team decides as a group when the code is ready for a release.
Typically, a release is done when we want to make changes available to users;
e.g., when some new functionality is sufficiently complete or we want users to
try something out and give us feedback early in the development process. A
release may also be done when some other development goal is reached. This
section describes how an Axom releases is done. The process is fairly
informal. However, we want to ensure that the software is in a reasonably
robust and stable state when a release is done. We follow this process to
release may also be done when some other development goal is reached. This
section describes how an Axom releases is done. The process is fairly
informal. However, we want to ensure that the software is in a reasonably
robust and stable state when a release is done. We follow this process to
avoid simple oversights and issues that we do not want to pass on to users.

In the :ref:`gitflow-label` section, we noted that the **master branch
Expand All @@ -25,75 +25,111 @@ whenever, the master branch is changed, it is tagged with a new
version number. We use a git 'lightweight tag' for this purpose. Such
a tag is essentially a pointer to a specific commit on the master branch.

We finalize preparations for a release on a release branch so that other
work may continue on the develop branch without interruption.
We finalize preparations for a release on a release branch so that other
work may continue on the develop branch without interruption.

.. note:: No significant code development is performed on a release branch.
In addition to preparing release notes and other documentation, the
only code changes that should be done are bug fixes identified
only code changes that should be done are bug fixes identified
during release preparations

Here are the steps to follow for an Axom release.

# **Create a release branch** off of the develop branch to finalize
the release. The name of a release branch must contain the associated
release version number. Typically, we use a name like rc0.5.0 (i.e.,
version 0.5.0 release candidate). See :ref:`semver-label` for a
description of how version numbers are chosen.
1: Start Release Candidate Branch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. **Create a pull request to merge the release branch into master** so that
release changes can be reviewed. Such changes include:
Create a release candidate branch off of the develop branch to initiate a
release. The name of a release branch must contain the associated release version
number. Typically, we use a name like v0.5.0-rc
(i.e., version 0.5.0 release candidate). See :ref:`semver-label` for a
description of how version numbers are chosen.

* Update the version information (major, minor, and patch version numbers)
at the top of the ``axom/src/cmake/AxomVersion.cmake`` file.
2: Issue a Pull Request
^^^^^^^^^^^^^^^^^^^^^^^^

* Test the code by running it through all continuous integration tests
and builds. This will ensure that all build configurations are working
properly and all tests pass.
Create a pull request to merge the release candidate branch into master so that
release changes can be reviewed. Such changes include:

* Fix any issues discovered during final release testing if code changes
are reasonably small and re-run appropriate tests to ensure issues are
resolved. If a major bug is discovered, and it requires significant
code modifications to fix, do not fix it on the release branch. Add
a JIRA issue for it and note the issue in the ``known bugs`` section of
the release notes.
#. Update the version information (major, minor, and patch version numbers)
at the top of the ``axom/src/cmake/AxomVersion.cmake`` file.

* Make sure all documentation (source code, user guides, etc.) is
updated and reviewed. This should not be a substantial undertaking as
most of this should have been done during the regular development cycle.
#. Update the release notes in ``axom/RELEASE-NOTES.md`` by adding the
release version number and release date in the heading, as well as,
the corresponding link to the version on Github.

* Proofread the release notes for completeness and clarity and address
any shortcomings. Again, this should not take much time as release notes
should be updated during the regular development cycle. See
:ref:`release-notes-label` for information about release notes.
#. Test the code by running it through all continuous integration tests
and builds. This will ensure that all build configurations are working
properly and all tests pass.

#. **Merge the release branch into the master branch** when the release
branch is ready and approved.
#. Fix any issues discovered during final release testing if code changes
are reasonably small and re-run appropriate tests to ensure issues are
resolved. If a major bug is discovered, and it requires significant
code modifications to fix, do not fix it on the release branch.
`Create a new Github issue for it <https://github.com/LLNL/axom/issues/new>`_
and note it in the ``known bugs`` section of the release notes.

#. **Tag the master branch with a new version number.** To tag master::
#. Make sure all documentation (source code, user guides, etc.) is
updated and reviewed. This should not be a substantial undertaking as
most of this should have been done during the regular development cycle.

$ git checkout master
$ git tag vMM.mm.pp
#. Proofread the release notes for completeness and clarity and address
any shortcomings. Again, this should not take much time as release notes
should be updated during the regular development cycle. See
:ref:`release-notes-label` for information about release notes.

Recall that 'MM' is the major version number, 'mm' is the minor version
number, and 'pp' is the patch number. The command::
3: Merge Release Candidate
^^^^^^^^^^^^^^^^^^^^^^^^^^^

$ git tag
Merge the release candidate branch into master branch once it is ready and
approved. At this point, the release candidate branch can be deleted.

will list all the tags and you should see the new tag you created.
The command::

$ git show vMM.mm.pp
4: Draft a Github Release
^^^^^^^^^^^^^^^^^^^^^^^^^

will show information about the tagged commit.
`Draft a new Release on Github <https://github.com/LLNL/axom/releases/new>`_

#. **Push the new tag to bitbucket.** You can push a single tag
to bitbucket by running the command ::
#. Enter the desired tag version, e.g., v0.5.0

$ git push vMM.mm.pp
#. Select **master** as the target branch to tag a release.

#. **Create a pull request to merge master into develop.** When approved,
merge it.
#. Enter a Release title. We typically use titles of the following form *Axom-v0.3.1*

#. Copy and paste the information for the release from the
``axom/RELEASE-NOTES.md`` into the release description (omit any sections if empty).

#. Publish the release. This will create a tag at the tip of the master
branch and add corresponding entry in the
`Releases section <https://github.com/LLNL/axom/releases>`_

.. note::

Github will add a corresponding tarbal and zip archives consisting of the
source files for each release. However, these files do not include any
submodules. Consequently, a tarball that includes all of the submodules is
generated manually in a seperate step.

5: Make a Release Tarball
^^^^^^^^^^^^^^^^^^^^^^^^^^

* Checkout the master branch locally and run the ``axom/scripts/make_release_tarball.sh``
script. This will generate a tarball of the form ``Axom-v0.3.1.tar.gz``

* Upload the tarball for the corresponding release, by going to the
`Github Releases section <https://github.com/LLNL/axom/releases>`_ and ``Edit``
the release created earlier.

* Attach the tarball to the release.

* Add a note at the top of the release description that indicates which
tarbal consists of all the submodules, e.g., *\"Please download the Axom-v0.3.1.tar.gz tarball below, which includes all of the Axom submodules as well\"*

* Update the release.

6: Merge Master to Develop
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a pull request to merge master into develop. When approved, merge it.


.. _release-notes-label:
Expand All @@ -103,17 +139,17 @@ Release Notes
*******************************************

Axom release notes are maintained in a single file ``axom/RELEASE-NOTES.md``.
The release notes for the latest version are at the top of the file.
Notes for previous releases appear after that in descending version number
The release notes for the latest version are at the top of the file.
Notes for previous releases appear after that in descending version number
order.

For each version, the release notes must contain the following information:

* Axom version number and date of release

* One or two sentence overview of release, including any major changes.
* Release note items should be broken out into the following sections:

* Release note items should be broken out into the following sections:

* Added: Descriptions of new features
* Removed: Notable removed functionality
Expand All @@ -122,34 +158,34 @@ For each version, the release notes must contain the following information:
* Fixed: Major bug fixes
* Known bugs: Existing issues that are important for users to know about

.. note:: Release notes for each Axom version should explain what changed in
that version of the software -- and nothing else!!
.. note:: Release notes for each Axom version should explain what changed in
that version of the software -- and nothing else!!

Release notes are an important way to communicate software changes to users
(functionality enhancements, new features, bug fixes, etc.). Arguably, they
are the simplest and easiest way to do so. Each change listed in the release
notes should contain a clear, concise statement of the change. Items should
be ordered based on the impact to users (higher impact - first, lower impact
last).
(functionality enhancements, new features, bug fixes, etc.). Arguably, they
are the simplest and easiest way to do so. Each change listed in the release
notes should contain a clear, concise statement of the change. Items should
be ordered based on the impact to users (higher impact - first, lower impact
last).

.. note:: When writing release notes, think about what users need to know and
what is of value to them.
.. note:: When writing release notes, think about what users need to know and
what is of value to them.

Release notes should summarize new developments and provide enough detail
for users to get a clear sense of what's new. They should be brief -- don't
make them overly verbose or detailed. Provide enough description for users
to understand a change, but no more than necessary. In other words, release
notes summarize major closed issues in a human-readable narrative. Direct
users to other documentation (user guides, software documentation, example
notes summarize major closed issues in a human-readable narrative. Direct
users to other documentation (user guides, software documentation, example
codes) for details and additional information.

.. note:: Release notes should be updated as work is completed and reviewed
along with other documentation in a pull request. This is much
easier than attempting to compile release notes before a release
by looking at commit logs, etc. Preparing release notes as part
along with other documentation in a pull request. This is much
easier than attempting to compile release notes before a release
by looking at commit logs, etc. Preparing release notes as part
of the release process should take no more than one hour.

Lastly, release notes provide an easy-to-find retrospective record of
Lastly, release notes provide an easy-to-find retrospective record of
progress for users and other stakeholders. They are useful for developers
and for project reporting and reviews.

Expand Down

0 comments on commit 807e93b

Please sign in to comment.