Adding an SCR section to the docs

doc/developer/first_time_contributors.rst

@@ -4,9 +4,9 @@ First Time Contributors Guide
 
 The ARMI team strongly encourages developers to contribute to the codebase.
 
-The ARMI framework code is open source, and your contributions will become open source.
-Although fewer laws apply to open source materials because they are publicly-available, you still
-must comply with all applicable laws and regulations.
+The ARMI framework code is open source, and your contributions will become open source. Although
+fewer laws apply to open source materials because they are publicly-available, you still must
+comply with all applicable laws and regulations.
 
 Help Wanted
 ===========
@@ -24,9 +24,8 @@ Naturally, you can also look at the open `ARMI issues <https://github.com/terrap
 Testing
 =======
 
-Any contribution must pass all included unit tests. You will frequently have to fix
-tests your code changes break. And you should definitely add tests to cover anything
-new your code does.
+Any contribution must pass all included unit tests. You will frequently have to fix tests your code
+changes break. And you should definitely add tests to cover anything new your code does.
 
 The ARMI tests are meant to be run using `pytest <https://docs.pytest.org/en/8.0.x/>`_
 locally ::
@@ -59,11 +58,11 @@ Also, please check out our (quick) synopsis on good commit messages: :ref:`armi-
 Licensing of Tools
 ==================
 
-Be careful when including any dependency in ARMI (say in the ``pyproject.toml`` file) not
-to include anything with a license that superceeds our Apache license. For instance,
-any third-party Python library included in ARMI with a GPL license will make the whole
-project fall under the GPL license. But a lot of potential users of ARMI will want to
-keep some of their work private, so we can't allow any GPL tools.
+Be careful when including any dependency in ARMI (say in the ``pyproject.toml`` file) not to include
+anything with a license that superceeds our Apache license. For instance, any third-party Python
+library included in ARMI with a GPL license will make the whole project fall under the GPL license.
+But a lot of potential users of ARMI will want to keep some of their work private, so we can't allow
+any GPL tools.
 
-For that reason, it is generally considered best-practice in the ARMI ecosystem to
-only use third-party Python libraries that have MIT or BSD licenses.
+For that reason, it is generally considered best-practice in the ARMI ecosystem to only use third-
+party Python libraries that have MIT or BSD licenses.

doc/developer/tooling.rst

@@ -27,20 +27,19 @@ The ARMI project follows a few basic rules for "good" commit messages:
 
 Good Pull Requests
 ==================
-A good commit is like a sentence; it expresses one complete thought. In that context, a good
-Pull Request (PR) is like a paragraph; it contains a few sentences that contain one larger
-thought. A good PR is *not* a chapter or an entire book! It should not contain multiple
-independent ideas.
+A good commit is like a sentence; it expresses one complete thought. In that context, a good Pull
+Request (PR) is like a paragraph; it contains a few sentences that contain one larger thought. A
+good PR is *not* a chapter or an entire book! It should not contain multiple independent ideas.
 
 One Idea = One PR
 -----------------
 .. important ::
     If you *can* break a PR into smaller PRs, containing unrelated changes, please do.
 
-It is a discourtesy to your reviewers to make them review a PR with multiple, unrelated changes.
-It forces them to look at every line of diff in your PR and figure out which change it belongs to.
-They are busy people, and it will save them time and effort if your PR only has one main idea.
-If your PRs are smaller, you will notice a great increase in the quality of the reviews you get.
+It is a discourtesy to your reviewers to make them review a PR with multiple, unrelated changes. It
+forces them to look at every line of diff in your PR and figure out which change it belongs to. They
+are busy people, and it will save them time and effort if your PR only has one main idea. If your
+PRs are smaller, you will notice a great increase in the quality of the reviews you get.
 
 Don't open until it is ready
 ----------------------------
@@ -51,18 +50,18 @@ Don't open until it is ready
 Your PR isn't complete when the code works, it is complete when the code is polished and all the
 tests are written and working. The idea here is: as soon as you open a PR, people will start
 spending their time looking at it. And their time is valuable. Even though GitHub allows you to
-`open a Draft PR <https://github.blog/2019-02-14-introducing-draft-pull-requests/>`_, this is
-not the default option in ARMI. It should not be your workflow to open a Draft PR by default. We
-prefer to keep the PR list as short as possible. A good rule of thumb is: don't open a PR until
-you think it is ready for final review.
+`open a Draft PR <https://github.blog/2019-02-14-introducing-draft-pull-requests/>`_, this is not
+the default option in ARMI. It should not be your workflow to open a Draft PR by default. We prefer
+to keep the PR list as short as possible. A good rule of thumb is: don't open a PR until you think
+it is ready for final review.
 
 Test It
 -------
 .. important ::
     If a PR doesn't have any changes to testing, it probably isn't complete.
 
-Unless a PR is just documentation or linting, it almost certainly needs testing to be complete.
-For example:
+Unless a PR is just documentation or linting, it almost certainly needs testing to be complete. For
+example:
 
 * If a PR adds new code, that code needs new tests to prove it is working.
 * If a PR changes existing code, there needs to be test changes to prove the code still works.
@@ -77,11 +76,11 @@ Document It
 .. important ::
     If it isn't documented, it doesn't exist.
 
-We auto-document the API, so don't worry about that. But when it comes to documentation, write
-it for somebody who is new to the code base 3 years from now, who needs to understand it in
-nitty-gritty detail to fix a bug without you. Think about variable names, comments, and docstrings.
-Also consider (if you are making a major change) that you might be making something in the docs
-out-of-date.
+We auto-document the API, so don't worry about that. But when it comes to documentation, write it
+for somebody who is new to the code base 3 years from now, who needs to understand it in nitty-
+gritty detail to fix a bug without you. Think about variable names, comments, and docstrings. Also
+consider (if you are making a major change) that you might be making something in the docs out-of-
+date.
 
 Watch for Requirements
 ----------------------
@@ -99,67 +98,74 @@ Such breadcrumbs will look like:
     """
 
 If you touch any code that has such a docstring, even at the top of the file, you are going to be
-responsible for not breaking that code/functionality. And you will be required to explicitly
-call out that you touch such a code in your PR.
+responsible for not breaking that code/functionality. And you will be required to explicitly call
+out that you touch such a code in your PR.
 
 Your PR reviewer will take an extra look at any PR that touches a requirement test or implementation.
-And you will need to add a special release note under the "Changes that Affect Requirements" section header.
+And you will need to add a special release note under the "Changes that Affect Requirements" section
+header.
+
 
 Add Release Notes
 -----------------
-For most PRs, you will need to add release notes to the
-`Release Notes documentation <https://github.com/terrapower/armi/tree/main/doc/release>`_. The goal
-here is to help track all the important changes that happened in ARMI, so ARMI can document what
-has changed during the next `release <https://github.com/terrapower/armi/releases>`_. To that end,
-minor PRs won't require a release note.
+For most PRs, you will need to add release notes to the :doc:`Release Notes </qa_docs/scr>`. The
+goal here is to help track all the important changes that happened in ARMI, so ARMI can document
+what has changed during the next release. To that end, every PR requires a release note.
+
+In particular, in the release notes, you will find four sections to choose from:
+
+1. **Code Changes, Features** - For changes that are actual, meaningful code changes.
+2. **Code Changes, Bugs and Fixes** - If the actual, meaningful change is specifical a bug fix or
+   something similar.
+3. **Code Changes, Maintenance, or Trivial** - If the change is not a meaningful code change, but
+   linting, formatting, variable name changes or similar.
+4. **Documentation-Only Changes** - If the change just touches documentation or in-code comments.
 
-In particular, in the release notes, you will find four sections in the release notes:
+If your PR fits more than one of these categories, just pick the one that applies that has the
+smallest number on the list above.
 
-1. **New Features** - A new feature (or major addition to a current feature) was added to the code.
-2. **API Changes** - ANY breaking change to the public-facing API of ARMI. (A breaking change is
-   when you change the existing API, not when you add something new to the API.)
-3. **Bug Fixes** - ANY bug fix in the code (not the documentation), no matter how minor.
-4. **Changes that Affect Requirements** - If you touch the code (``impl``) or test (``test``) for
-   anything that currently has a requirement crumb. (This must be a non-trivial change.)
+An important column in the Release Notes is "Changes to Requirements". This is the place to call
+out all the requirements that you touched. That is, if you touched the requirement in the
+documentation, or the code that implements that requirement which is marked by an "`impl`" tag, or
+even a requirement tests marked by a "`test`" tag. We want to make sure and document every time we
+touch a requirement some way in a PR.
 
-If your PR fits more than one of these categories, great! Put a description of your change under
-all the categories that apply.
+If you do not touch a requirement put "NA" in that column.
 
 
 Packaging and dependency management
 ===================================
-The process of packaging Python projects and managing their dependencies is somewhat
-challenging and nuanced. The contents of our ``pyproject.toml`` follow existing conventions as
-much as possible. In particular, we follow `the official Python packaging guidance
+The process of packaging Python projects and managing their dependencies is somewhat challenging and
+nuanced. The contents of our ``pyproject.toml`` follow existing conventions as much as possible. In
+particular, we follow `the official Python packaging guidance
 <https://packaging.python.org/en/latest/>`_.
 
 pyproject.toml
 --------------
-As much as possible, the ARMI team will try to centralize our installation and build systems
-through the top-level ``pyproject.toml`` file. The only exception will be our documentation,
-which has much customization done through the Sphinx ``doc/conf.py`` file.
+As much as possible, the ARMI team will try to centralize our installation and build systems through
+the top-level ``pyproject.toml`` file. The only exception will be our documentation, which has much
+customization done through the Sphinx ``doc/conf.py`` file.
 
-The packages listed in the ``install_requires`` argument to ``setup()`` are meant to
-express, as abstractly as possible, the packages that need to be installed **somehow**
-for the package to work. In addition, ``extras_require`` are used to specify other
-packages that are not strictly required, but if installed enable extra functionality,
-like unit testing or building documentation.
+The packages listed in the ``install_requires`` argument to ``setup()`` are meant to express, as
+abstractly as possible, the packages that need to be installed **somehow** for the package to work.
+In addition, ``extras_require`` are used to specify other packages that are not strictly required,
+but if installed enable extra functionality, like unit testing or building documentation.
 
 Third-Party Licensing
 ---------------------
-Be careful when including any dependency in ARMI (say in the ``pyproject.toml`` file) not
-to include anything with a license that supercedes our Apache license. For instance,
-any third-party Python library included in ARMI with a GPL license will make the whole
-project fall under the GPL license. But a lot of potential users of ARMI will want to
-keep some of their work private, so we can't allow any GPL tools.
+Be careful when including any dependency in ARMI (say in the ``pyproject.toml`` file) not to include
+anything with a license that supercedes our Apache license. For instance, any third-party Python
+library included in ARMI with a GPL license will make the whole project fall under the GPL license.
+But a lot of potential users of ARMI will want to keep some of their work private, so we can't allow
+any GPL tools.
 
-For that reason, it is generally considered best-practice in the ARMI ecosystem to
-only use third-party Python libraries that have MIT or BSD licenses.
+For that reason, it is generally considered best-practice in the ARMI ecosystem to only use third-
+party Python libraries that have MIT or BSD licenses.
 
 Releasing a New Version of ARMI
 ===============================
-We use the common ``major.minor.bump`` version scheme where a version string
-might look like ``0.1.7``, ``1.0.0``, or ``12.3.123``. Each number has a specific meaning:
+We use the common ``major.minor.bump`` version scheme where a version string might look like
+``0.1.7``, ``1.0.0``, or ``12.3.123``. Each number has a specific meaning:
 
 * ``major`` - Revved for DOE/NRC-sanctioned release or at the end of a long development cycle.
 * ``minor`` - Revved when we decide the code or our API has reached a stable point.
@@ -169,10 +175,9 @@ might look like ``0.1.7``, ``1.0.0``, or ``12.3.123``. Each number has a specifi
 
 **Any change to a major or minor version is considered a release.**
 
-Only a core member of the ARMI team may release a new version, or add a tag of any kind to
-the repository. The rule is *the only tags in the ARMI repo are for official versions*. If
-you want to release a version of ARMI, you will need admin privileges to multiple TerraPower
-repos on GitHub.
+Only a core member of the ARMI team may release a new version, or add a tag of any kind to the
+repository. The rule is *the only tags in the ARMI repo are for official versions*. If you want to
+release a version of ARMI, you will need admin privileges to multiple TerraPower repos on GitHub.
 
 Every release should follow this process:
 
@@ -188,8 +193,8 @@ Every release should follow this process:
     - **NOTE** - The ONLY tags in the ARMI repo are for official version releases.
 
 5. Also add the release notes on `the GitHub UI <https://github.com/terrapower/armi/releases>`__.
-6. Follow the instructions `here <https://github.com/terrapower/terrapower.github.io>`_ to
-   archive the new documentation.
+6. Follow the instructions `here <https://github.com/terrapower/terrapower.github.io>`_ to archive
+   the new documentation.
 7. Tell everyone!
 
 Logging with runLog
@@ -282,7 +287,8 @@ The ``runLog`` tool also allows for you to log one module differently from the r
 base. For instance, you could set the log level to "debug" in just one Python file, to help testing
 during development.
 
-That functionality is provided by what might look like a bare Python logging import, but is actually calling the same underlying ``armi`` logging tooling:
+That functionality is provided by what might look like a bare Python logging import, but is actually
+calling the same underlying ``armi`` logging tooling:
 
 .. code-block:: python
 

doc/qa_docs/scr/0.6.rst

@@ -0,0 +1,115 @@
+SCR Listing for ARMI version 0.6.0
+==================================
+
+This is a listing of all the Software Change Request (SCR) changes in the ARMI repository, as part
+of release number 0.6.0.
+
+Please note that the Software Test Report (STR) documents for all of the changes listed below will
+be updated as part of this release. This is a necessary part of every ARMI release, that the STRs
+are all updated.
+
+Below, this SCR is organized into the individual changes that comprise the net SCR for this release.
+
+
+Code Changes, Features
+^^^^^^^^^^^^^^^^^^^^^^
+
+The following software changes added new features, or made a meaningful to change to an existing one.
+
+.. list-table:: Code Changes, Features
+   :widths: 20 25 25 15 15 10 10
+   :header-rows: 1
+
+   * - Title
+     - Change
+     - | Impact on
+       | Requirements
+     - Author(s)
+     - Approver(s)
+     - Issue(s)
+     - PR(s)
+   * - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+
+
+Code Changes, Bugs and Fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following software changes related to bugs or other fixes.
+
+.. list-table:: Code Changes, Bugs and Fixes
+   :widths: 20 25 25 15 15 10 10
+   :header-rows: 1
+
+   * - Title
+     - Change
+     - | Impact on
+       | Requirements
+     - Author(s)
+     - Approver(s)
+     - Issue(s)
+     - PR(s)
+   * - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+
+
+Code Changes, Maintenance, or Trivial
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This selection collects more trivial software changes. Such a change might fall into a usual "maintenance" bin. It is probably part of the continuous and on-going technical debt efforts. But the change might be as minor as linting.
+
+.. list-table:: Code Changes, Maintenance, or Trivial
+   :widths: 20 25 20 15 15 10 10
+   :header-rows: 1
+
+   * - Title
+     - Change
+     - | Impact on
+       | Requirements
+     - Author(s)
+     - Approver(s)
+     - Issue(s)
+     - PR(s)
+   * - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+
+
+Documentation-Only Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following changes below are changes to the SRSD, SDID, STR, or other SQA documentation.
+
+.. list-table:: Documentation-Only Changes
+   :widths: 20 25 25 15 15 10 10
+   :header-rows: 1
+
+   * - Title
+     - Change
+     - | Impact on
+       | Requirements
+     - Author(s)
+     - Approver(s)
+     - Issue(s)
+     - PR(s)
+   * - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD
+     - TBD

doc/qa_docs/scr/index.rst

@@ -0,0 +1,14 @@
+########################
+Software Change Requests
+########################
+
+You can find a Software Change Request (SCR) for each releases below.
+
+----------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :reversed:
+
+   *