Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : 
       6             : # Automatic versioning {#dev_guide_automatic_versioning}
       7             : 
       8             : \tableofcontents
       9             : 
      10             : Our automated tests can tag and publish a release automatically when requested.
      11             : The automation is implemented as a [GitHub
      12             : Actions](https://docs.github.com/actions) workflow in the file
      13             : `.github/workflows/Tests.yaml`.
      14             : 
      15             : ## Creating releases
      16             : 
      17             : The GitHub workflow responsible for automated testing also allows creating a
      18             : release when dispatched manually. To create a release (roughly on the first
      19             : Monday of each month and/or when needed for publications), follow these
      20             : instructions:
      21             : 
      22             : 1. **Check for bugs on `develop`.** If you are aware of any major bugs in the
      23             :    code on `develop`, check with the (other) core developers if it would be
      24             :    better to wait with the release until those bugs are fixed.
      25             : 2. **Check the release notes.** Find the latest run of the [`Tests` workflow
      26             :    on the `develop` branch](https://github.com/sxs-collaboration/spectre/actions/workflows/Tests.yaml?query=branch%3Adevelop). Select the "Files and formatting" job and the
      27             :    "Print release notes" step within. Go through the release notes, checking
      28             :    the following in particular:
      29             :    - Label bugfix PRs with the `bugfix` label so they appear in the "Bugfixes"
      30             :      section and don't clutter the list.
      31             :    - Label PRs that you want to highlight with the `new feature` label, so they
      32             :      appear at the top. The selection is up to you.
      33             :    - Add upgrade instructions to PRs where they are missing, to help other
      34             :      developers with rebasing their code.
      35             : 3. **Dispatch the release.** Go to the GitHub Actions page for the [`Tests`
      36             :    workflow](https://github.com/sxs-collaboration/spectre/actions/workflows/Tests.yaml?query=branch%3Adevelop).
      37             :    [Select "Run workflow"](https://docs.github.com/actions/managing-workflow-runs/manually-running-a-workflow)
      38             :    and the `develop` branch. Type in a valid release version name, such as
      39             :    "2021.05.04", and hit "Run workflow". The release will only be created if
      40             :    if the version name matches the format defined in
      41             :    \ref versioning_and_releases _and_ if it matches the current date. Therefore,
      42             :    if you wait too long with the next step, the release will fail and you have
      43             :    to dispatch it again.
      44             : 
      45             :    It is probably best to hold off merging PRs while the release workflow runs,
      46             :    to avoid possible conflicts. Therefore, warn the (other) core devs.
      47             : 4. **Ask for approval.** Once the unit tests are complete, the release workflow
      48             :    will wait for approval before publishing the release on GitHub and Zenodo.
      49             :    Notify the (other) core devs so one of them can review and approve the
      50             :    release (don't approve the release yourself). You can point them to these
      51             :    guidelines:
      52             : 
      53             :    Guidelines for reviewing a release:
      54             :    - Check for bugs on `develop` (see point 1. above).
      55             :    - Check the release notes (see point 2. above).
      56             : 
      57             : ## Release notes
      58             : 
      59             : The release notes are compiled automatically based on the activity in the
      60             : repository since the last release. They will contain a list of merged
      61             : pull-requests. Pull-requests labeled "new feature" or "bugfix" on GitHub
      62             : will be classified as such in the release notes.
      63             : 
      64             : The script `tools/CompileReleaseNotes.py` generates the release notes and can
      65             : also be invoked manually with a Python 3 interpreter to retrieve an overview of
      66             : what happened in the repository recently. The script requires you install
      67             : `GitPython`, `PyGithub` and `tqdm` in your Python environment.