Release v0.4.0 (celeritas-project#1031)

* Add pull request template and document labels

* Add pull request template for releases

* Fix documentation

* Update latex pdf header to include institutions

* Move rst file locations

* Add release documentation

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+**Please read, follow, and delete this text**
+
+# Title
+
+Should be an imperative statement (title-cased first word,
+no trailing punctuation) summarizing its effect on the user.  For example:
+ - Implement the FooBar model *[enhancement, physics]*
+ - Handle errors in track initialization *[enhancement, orange]*
+ - Fix sampling of low-energy Celeritons *[bug, physics]*
+ - Refactor code in preparation for new tracker type *[minor, orange]*
+ - Add CI support for multiple Geant4 versions *[enhancement, documentation]*
+
+# Description
+
+The description should summarize or enumerate the main changes in the pull
+request. Illustrative images are recommended if possible!
+
+# Labels
+
+If you're a core developer, add one of each label:
+
+- Change type: {bug, documentation, enhancement, minor}
+- Category: {app, core, external, field, orange, performance, physics,
+  user}
+
+See [https://github.com/celeritas-project/celeritas/blob/develop/doc/appendices/administration.rst#review-process](review process) for descriptions of the labels and requirements.

.github/pull_request_template.release.md

@@ -0,0 +1,26 @@
+<!--
+Title: "Release vX.Y.Z"
+Target: upstream/develop (always!)
+-->
+
+**Release branches must be named `release-vX.Y.Z`**
+
+## Pre-merge checklist
+
+- [ ] Ensure all CI jobs on develop pass
+- [ ] Tag the develop branch with ``vX.Y.Z-rc.N`` where N starts with 1, and increment for every time you return to this step due to new pull requests.
+- [ ] Run performance regression tests on Summit, Crusher/Frontier, and an additional machine with debug assertions enabled (e.g., Wildstyle).
+- [ ] Update documentation with release notes from all pull requests newly included in the release.
+- [ ] Ensure the code documentation builds with as few warnings as possible in the `doc` workflow on the CI.
+
+## Post-merge checklist
+
+- [ ] If releasing a backported version branch, cherry-pick this documentation commit into the backport branch.
+- [ ] Use the [GitHub interface](https://github.com/celeritas-project/celeritas/releases/new) to create a new release with the documentation update that was just added.
+
+## Post-release checklist
+
+- [ ] Save the ``tar.gz`` and attach to the release, because the hash changes if the git "describe" function returns a different result for the release tag's hash (e.g., if a collaborative branch on the main repository points to that commit).
+- [ ] Pull locally (make sure to use the ``--tags`` option) and build PDF user documentation for the release. Ensure breathe is activated (so the API is listed) and that the version is embedded correctly.
+- [ ] Update the Spack recipe for Celeritas with the new version and sha256 value (either manually or using ``spack checksum``) and submit a [pull request to the Spack project](https://github.com/spack/spack/pull).
+- [ ] Mark the GitHub [release milestone](https://github.com/celeritas-project/celeritas/milestones) as completed.

CONTRIBUTING.rst

@@ -74,11 +74,8 @@ and :ref:`style <style_guidelines>` guidelines have been followed for all new
 code and code changes.  Ensure the use of the correct formatting as well as the
 addition of documentation and unit tests for new code and bug fixes.
 
-All tests must pass on the CI runner before a PR can be merged. (Exceptions
-will be made if any failures are clearly unrelated to the changes and enough
-tests and/or configuration are passing to show that the new code is working.
-For example, some of the configurations have a tendency to fail due to disk
-space issues.) It's best to test locally first before submitting your pull
+All tests must pass on the CI runner before a PR can be merged. It's best to
+test locally first before submitting your pull
 request, and keep in mind that the multiple configurations on the CI (different
 dependency versions, different features) may reveal failures that your local
 testing might have missed.

doc/CMakeLists.txt

@@ -232,8 +232,8 @@ celeritas_build_sphinx(latex "${_doc_tex}")
 if(Sphinx_FOUND)
   # Download ornltm class
   ExternalProject_Add(ornltm
-    GIT_REPOSITORY https://code.ornl.gov/s3j/ornltm.git
-    GIT_TAG 05a4b22f104abd53ac7cae72fe03768710b56b86
+    GIT_REPOSITORY https://code.ornl.gov/sethrj/ornltm.git
+    GIT_TAG c9d2ddcce2bfc8d7d51db8f4a131d71883f46528
     CONFIGURE_COMMAND ""
     BUILD_COMMAND ""
     INSTALL_COMMAND ""

doc/_static/ornltm-header-celeritas.tex

@@ -1,19 +1,53 @@
 \documentclass{ornltm}
 
-\author{Seth R.~Johnson
-\and Philippe Canal (FNAL)
-\and Julien Esseiva (LBNL)
-\and Thomas M.~Evans
-\and Soon Yung Jun (FNAL)
-\and Guilherme Lima (FNAL)
-\and Amanda Lund (ANL)
-\and Paul Romano (ANL)
-\and Stefano C.~Tognini
-\and Ben Morgan (Univeristy of Warwick)
+\author{%
+  Seth R.~Johnson\affilnum{1}%
+  %%
+  \and
+  Elliott Biondo\affilnum{1}
+  %%
+  \and
+  Julien Esseiva\affilnum{4}
+  %%
+  \and
+  Soon Yung Jun\affilnum{2}
+  %%
+  \and
+  Guilherme Lima\affilnum{2}
+  %%
+  \and
+  Amanda Lund\affilnum{3}
+  %%
+  \and
+  Ben Morgan\affilnum{5}
+  %%
+  \and
+  Stefano C.~Tognini\affilnum{1}
+  %%
+  \and
+  Philippe Canal\affilnum{2}
+  %%
+  \and
+  Marcel Demarteau\affilnum{1}
+  %%
+  \and
+  Thomas Evans\affilnum{1}
+  %%
+  \and
+  Paul Romano\affilnum{3}
+}%
+
+\affiliation{%
+    \affilnum{1}Oak Ridge National Laboratory, Oak Ridge, TN, USA \\
+    \affilnum{2}Fermi National Accelerator Laboratory, Batavia, IL, USA \\
+    \affilnum{3}Argonne National Laboratory, Lemont, IL, USA \\
+    \affilnum{4}Lawrence Berkeley National Laboratory, Berkeley, CA, USA \\
+    \affilnum{5}University of Warwick, Coventry, United Kingdom%
 }
+
 \title{Celeritas User Manual}
-\date{Jul.~2023}
-\reportnum{ORNL/TM-2023/XXXX}
+\date{Jan.~2024}
+\reportnum{ORNL/TM-2024/XXXX}
 \reportdraft
 \division{Computational Sciences and Engineering Division}
 

doc/appendices/administration.rst → doc/appendix/administration.rst

@@ -98,8 +98,8 @@ increasing the `bus factor`_.
 
 .. _bus factor: https://en.wikipedia.org/wiki/Bus_factor
 
-Review process
---------------
+Reviewing pull requests
+-----------------------
 
 Each pull request must be reviewed by at least one
 member of the :ref:`core team <roles>` who is knowledgeable about
@@ -132,22 +132,122 @@ followed in the new code. Balance the desire for readability with the need to
 avoid bikeshedding_ by asking yourself whether your requests are
 substantive enough to merit a new pull request. Perfect is the enemy of good.
 
+Check that the title meets the requirements below, that the description is
+adequate, and that the appropriate labels are set.
+
 By the time you've finished the code review, you should understand the code
 well enough to maintain it (by extension or modification) in the future.
 
 .. _bikeshedding: https://thedecisionlab.com/biases/bikeshedding
 
+PR titles
+^^^^^^^^^
+
+The title should be an imperative statement (title-cased first word,
+no trailing punctuation) summarizing its effect on the user.  For example:
+
+ - Implement the FooBar model *[enhancement, physics]*
+ - Handle errors in track initialization *[enhancement, orange]*
+ - Fix sampling of low-energy Celeritons *[bug, physics]*
+ - Refactor code in preparation for new tracker type *[minor, orange]*
+ - Add CI support for multiple Geant4 versions *[enhancement, documentation]*
+
+Avoid tags in the title.
+
+PR description
+^^^^^^^^^^^^^^
+
+The description should summarize or enumerate the main changes in the pull
+request. Illustrative images are recommended if possible!
+
+Label descriptions
+^^^^^^^^^^^^^^^^^^
+
+The labels_ used in Celeritas GitHub pull requests and issues have specific
+meanings. There should be one "change type" and one "category" selected. A few
+special labels ("backport", "performance") can also be added when appropriate.
+
+Change type
+"""""""""""
+
+The change types are used to categorize changes in the release notes. If a pull
+request seems like it should have multiple change types, it should probably be
+broken up into multiple pull requests.
+
+Bug
+   Report or fix an error that a user could encounter.
+
+Documentation
+   Add new tests, documentation, or personal user presets *without* any changes
+   in the library or applications.
+
+Enhancement
+   Request or add something new to the code.
+
+Minor
+   Refactor code or make small changes that should be effectively invisible to
+   users and probably not reported.
+
+Category
+""""""""
 
-Merge process
--------------
+These should be fixes, changes, or enhancements to support...
+
+App
+   front end applications (``celer-g4`` and ``celer-sim``).
+
+Core
+   core infrastructure such as platform portability.
+
+External
+   integration with external libraries such as Geant4, VecGeom, and ROOT.
+
+Field
+   magnetic field propagation, linear propagation, and safety distance
+   calculation.
+
+ORANGE
+   the Celeritas geometry library for GPU tracking.
+
+Performance
+   performance optimization on GPU and CPU.
+
+Physics
+   particles, processes, and stepping algorithms.
+
+User
+   hits and track diagnostics (i.e., extracting data from tracks running on the
+   GPU).
+
+
+.. _labels: https://github.com/celeritas-project/celeritas/labels
+
+Merging
+-------
+
+The GitHub settings for Celeritas currently require that before merging:
+
+1.  The branch must be up-to-date with upstream develop. This ensures that
+    there are no failures from "implicit" conflicts (where no code actually
+    generates a git conflict, but some new requirement or change upstream
+    has not been implemented in the new branch). An "Update branch" button is
+    available on the pull request page to ensure this requirement is met.
+2.  The GitHub Action CI checks must pass. There are a small matrix of core
+    combinations that cover most potential build issues. These do not *execute*
+    GPU code but they will build it and ensure that the tests pass when
+    the Celeritas device capability is disabled.
 
 Celeritas uses the "squash and merge" process to ensure continuity of the code
 history and provide easy bisecting because all commits pass all tests.
 Squashing eliminates the potential of broken commits and relieves developers of
 the burden of worrying about clean commit messages within a branch.
 
 Since there are few enough merge requests these days, only :ref:`maintainers
-<roles>` may commit a merge.
+<roles>` may commit a merge. When merging, check that the commit title matches
+the issue title (it may be inconsistent if the branch has only a single
+commit), and that the "co-author" tags at the bottom of the commit message
+accurately reflect contributions (co-authorship may be erroneously attributed
+for a simple merging of the main branch into the development branch).
 
 
 Releases
@@ -175,6 +275,9 @@ other major code changes.
 Release process
 ---------------
 
+.. ***NOTE*** when changing this section, make sure
+   ``.github/pull_request_template.release`` is also updated.
+
 Releases can be created from the primary "develop" branch (major, minor, patch)
 or a "backport" branch (minor, patch).
 The following process must be followed (and may need iteration to converge) for
@@ -193,9 +296,9 @@ each release.
     `helper notebook`_ in the Celeritas documents repository to automate this.
 4.  Tag the branch on your fork with ``vX.Y.Z-rc.N`` where N starts with 1, and
     increment for every time you return to this step due to new pull requests.
-5.  Run regression tests on Summit (for performance testing), Crusher (for HIP
-    testing), and an additional machine with debug assertions enabled (e.g.,
-    Wildstyle).
+5.  Run performance regression tests on Summit (for performance testing),
+    Crusher/Frontier (for HIP testing), and an additional machine with debug
+    assertions enabled (e.g., Wildstyle).
 6.  [TODO: define high-level validation tests like `geant-val`_ and a test
     matrix correlating capability areas (code files/directories changed) to
     test names.] Rerun and perform a cursory check on all validation tests that

doc/appendices/release-history.rst → doc/appendix/release-history.rst

@@ -12,6 +12,7 @@ Release History
    :maxdepth: 2
    :caption: Appendices
 
+   release-history/v0.4.rst
    release-history/v0.3.rst
    release-history/v0.2.rst
    release-history/v0.1.rst