CEP 3 - Cyclus Release Procedure

CEP:

3

Title:

Cyclus Release Procedure

Last-Modified:

2017-11-06

Author:

Anthony Scopatz and Matthew Gidden and Baptiste Mouginot

Status:

Accepted

Type:

Process

Created:

2013-10-25

Abstract

The purpose of this document is to act as a guideline and checklist for how to release the Cyclus core code base and the supported projects in the ecosystem.

The Cyclus Ecosystem

The very first thing to do when preparing for an upcoming release is to elect a release manager. This person has the special responsibility of making sure all of the following tasks are implemented. Therefore, their judgment for the placement of issues and code stability must be adhered to.

The Cyclus ecosystem has a few projects which are all released together. (This may change in the future a development diverges and the core becomes more stable.) The projects that are under the release manager’s purview are:

• Cyclus

• Cycamore

• Cymetric

The projects which are not yet under the release managers purview are:

• Rickshaw

• CyclusJS

Note

The following full release process only applies to MAJOR and MINOR release number changes. MICRO or PATCH releases may be performed with a version bump and a git tag alone. This is to enable fast turn arounds for bug fixes and binary package creation (ie deb or conda). Therefore versions with a non-zero MICRO number should be considered relatively unstable.

Release Candidates (Tags & Branches)

At the beginning of a release, a special branch for each project should be made off of master named vX.X.X-release. Note the v at the beginning. Each project should have the initial version of of it’s release branch tagged as X.X.X-rc1, the first release candidate.

Note

To distingush them, branch names have a v prefix (vX.X.X-release) while tag names lack this prefix (X.X.X-rcX).

Release candidates serve as an official proving ground for the release. Upon creation, an announcement should be made to the developer’s list, and users of the project should be encouraged to test them out in order to bugs/other issues.

Any required changes must be pull requested from a topical branch into the release branch. After this has been accepted, the topical branch must be merged with master as well. The release branch is there so that development can continue on the master branch while the release candidates (rc) are out and under review. This is because otherwise any new developments would have to wait until post-release to be merged into master to prevent them from accidentally getting released early.

Everything that is in the release branch must also be part of master. Graphically,

Figure 1: Branch hierarchy under release.

Note

Any commits merged into the release branch must also be merged into master. It is common practice for the release manager to request the reviewer pull requests to merge the topical branch into master as well. However, it is the ultimate release manager’s responsibility to make sure master is kept up to date with the release branch.

If changes are made to the release branch, a new candidate must be issued after 2 - 5 days. Every time a new release candidate comes out the vX.X.X-release must be tagged with the name X.X.X-rcX. A developer’s list annoucement must accompany any new candidate.

The release branch must be quiet and untouched for 2 - 5 days prior to the full release. When the full and final release happens, the vX.X.X-release branch is deleted. All commits in the vX.X.X-release branch must have also been merged into the master branch as they were accepted.

Project Checklist

Note

Utility scripts for this process can be found in the release repository

Releasing a Cyclus project is comprised of the following operations. Each operation should be enacted in order.

Release Candidate Process

1. Review ALL issues and pull requests, reassigning or closing them as needed.

2. Ensure that all issues/PRs in this release’s milestone have been closed. Moving them to the next release’s milestone is a perfectly valid strategy for completing this milestone.

3. Initiate the release candidate process (see above)

4. Review the current state of documentation and make approriate updates.

5. Finish the release candidate process

   • make sure all commits in the release branch also are in master

Release Process

1. Make sure every local Cyclus project repository is up to date with its master, and vX.X.X-release branches on upstream.

2. Bump the version in cyclus/src/version.h.in and cyclus/cyclus/__init__.py, cycamore/src/cycamore_version.h.in, and cymetric/setup.py; commit the changes

3. Perform maintenance tasks for all projects. The maintenance depends on PyNE and Doxygen. Maintenance files can be found here.

   • they are described in detail below, but the maintenance.sh utility in release/utils will do this automatically for you

   • make sure to have your rs.cred file (see maintenance.sh’s help)

   $ cd /path/to/release/utils
   $ export CYCLUS_DIR=/path/to/cyclus
   $ export CYCAMORE_DIR=/path/to/cycamore
   $ ./maintenance.sh -r -v X.X.X # X.X.X is *this* version
   

   Note

   If maintenance script fails because of an ABI failure that is caused by a compiler update (or other similar change caused by reasons other than code changes), you might want to accept them and procceed with the release with those. To do so you need to generate the new symbols and commit them:

   1. First make sure those changes can be ignored by emailing for discussion/approval the dev-list

   2. if the dev-list agrees to those changes, update the symbols and commit the new one:

   $ cd $CYCLUS_DIR/release
   $ ./smbchk.py --update -t X.X.X # X.X.X is *this* version
   $ git add symbols.json
   $ git commit -m "Describe here all the change on the ABI"
   

4. Commit all changes for all projects.

   $ cd /path/to/project
   $ git checkout vX.X.X-release
   $ git commit -am "final release commit after maintenence"
   

5. Update all master branches.

   $ cd /path/to/project
   $ git checkout master
   $ git merge --no-ff vX.X.X-release
   $ git push upstream master
   

6. Locally tag the repository for each of the projects.

   $ cd /path/to/project
   $ git checkout master
   $ git merge --no-ff vX.X.X-release
   $ git tag -a -m "Cyclus project release X.X.X, see http://fuelcycle.org/previous/vX.X.X.html for release notes" X.X.X
   

7. Draft release notes.

   • the make_release_notes.sh utility in release/utils will help provide a template

   $ cd /path/to/release/utils
   $ export CYCLUS_DIR=/path/to/cyclus
   $ export CYCAMORE_DIR=/path/to/cycamore
   $ export CYMETRIC_DIR=/path/to/cymetric
   $ ./make_release_notes.sh W.W.W X.X.X # W.W.W is the previous version, X.X.X is *this* version
   

   • add the release notes as cyclus.github.com/source/previous/vX.X.X.rst with appropriate updates to index.rst in that directory

8. Update the API docs.

   • the api_docs.sh utility in release/utils will do this automatically for you

   $ cd /path/to/release/utils
   $ export CYCLUS_DIR=/path/to/cyclus
   $ export CYCAMORE_DIR=/path/to/cycamore
   $ ./api_docs.sh X.X.X # X.X.X is *this* version
   

9. Update the master branch of all projects and clean up.

   $ cd /path/to/project
   $ git push upstream X.X.X master
   $ git push upstream --delete vX.X.X-release
   

10. Manually visit the github.com page for each project and draft/publish a new release.

    • See instructions here

11. Update Conda-forge

    • For each project, find the corresponding feedstock repository in the conda-forge organization on github. For example, cyclus’ feedstock is at https://github.com/conda-forge/cyclus-feedstock

    • In each project’s feedstok, open up a PR which updates the recipe/meta.yaml file with the new version number and the new SHA-256 value of the new version’s tarball. See conda-forge documentation for more or ask the feedstock maintainers for help.

    • Note that each feedstock must be accepted and the package uploaded to anaconda.org (automatic) prior to accepting updates for the next feedstock dependency. For example, cyclus must be fully updated before cycamore.

12. Create a DOI. See CEP4 for details.

    • This can be updated one day to use the Figshare API

13. Update website release information.

    • on the front page (source/index.rst)

    • DOIs (source/cite/index.rst)

    • release notes (source/previous/index.rst), remember both the release notes and the zip/tar URLs!

    • layout template (source/atemplates/layout.html) of the website

    • install from tarball instruction (source/user/install_from_tarball.rst)

14. Commit all changes to cyclus.github.com and make gh-publish

15. Send out an email to cyclus-dev and cyclus-users to announce the release!

Maintainence Tasks

Note

There is now the maintenence.sh utility in release/utils that will automate this for you. The section remains here for posterity.

Each project may have associate maintenance tasks which may need to be performed at least as often as every micro release.

Cyclus

Update PyNE: PyNE source code is included and shipped as part of Cyclus. As pyne evolves, we’ll want to have our version evolve as well. Here are the steps to do so. These assume that in your HOME dir there are both the pyne and Cyclus repos. Remember to check in the changes afterwards.

$ cd ~/pyne
$ ./amalgamate.py -s pyne.cc -i pyne.h
$ cp pyne.* ~/cyclus/src

Update Nuclear Data: PyNE also provides a nuclear data library generator which we use for our source data. Occassionally, this needs to be updated as updates to pyne itself come out. The command for generating Cyclus specific nuclear data is as follows:

$ cd ~/pyne
$ nuc_data_make -o cyclus_nuc_data.h5 \
 -m atomic_mass,scattering_lengths,decay,simple_xs,materials,eaf,wimsd_fpy,nds_fpy

Once the file is generated it must be put onto rackspace.

Update Gtest: We include a copy of the fused Gtest source code within our source tree located in the tests/GoogleTest directory. To keep up with Gtest’s natural evolution cycle, please download the latest release of Google Tests and follow the fused source directions here. If we go too long without doing this, it could be very painful to update.

Verify & Update API Stability: Since Cyclus v1.0 we promise API stability. Luckily, we have a tool for keeping track of this mostly automatically. In order to check this correctly, you must have a RELEASE build of Cyclus compiled/installed. Every release please run the following command to verify that the release branch is stable:

$ cd cyclus/release
$ ./smbchk.py --update -t HEAD --no-save --check

If Cyclus only has API additions, it is considered stable and the command will tell you so. If Cyclus also has API deletions, then Cyclus is considered unstable and a diff of the symbols will be printed. You cannot release |cyclus| if it is unstable! Please post the diff to either the mailing list or the issue tracker and work to resolve the removed symbols until it this command declares that Cyclus is stable. It is probably best to do this prior to any release candidates if possible.

Once stable and there are no more code changes to be made, add the symbols in this release to the database with the following command (again - make sure you are working on a RELEASE build of Cyclus):

$ cd cyclus/release
$ ./smbchk.py --update -t X.X.X

where X.X.X is the version tag. This should alter the symbols.json file. Commit this and add it to the repo.

Cycamore

No maintenence required.

Cymetric

No maintenance required.

Document History

This document is released under the CC-BY 3.0 license.