Update Release Instructions (#329)

* Update language from users to developers * update issue status on release planner * fix issues * add reviwer instructions * add release planner description * update procedure * add changelog * add ReadTheDocs instructions * reminder to squash and merge * fix version label * edit language * update instructions on PRs and issues * Fix typo * Fix typo * Fix typo * Fix typo * add reference to branches in git section * Add instructions on which branch to merge into --------- Co-authored-by: Nathan Petersen <[email protected]>
Severson-Group · Jan 24, 2024 · 65ac91b · 65ac91b
1 parent 8c9d730
commit 65ac91b
Show file tree

Hide file tree

Showing 2 changed files with 75 additions and 13 deletions.
diff --git a/docs/source/contribution.rst b/docs/source/contribution.rst
@@ -50,14 +50,25 @@ Git/GitHub Usage
 -------------------------------------------
 
 All code development should occur within the Git version control environment. When code is ready to be contributed back 
-to eMach, users should open a Pull Request (PR) on GitHub which explains their contribution.
+to eMach, developers should open a Pull Request (PR) on GitHub which explains their contribution. 
 
+Pull Requests and Issues
+++++++++++++++++++++++++++++++++++++++++++++
+The PR must close at least one issue
+and all important aspects of the PR need to be described in one or more issues closed by the PR. 
+PRs should not partially complete issues, and developers may need to break issues up into multiple issues to ensure that this is true. 
+The developer should schedule each issue being closed onto the appropriate release by updating the issue status on the `eMach Release Planner <https://github.com/orgs/Severson-Group/projects/26/views/1>`_.
+
+Developers should also consider which branch their PR should merge into based on eMach's Maintainer Guidelines :any:`branches-in-git`. PRs should nearly always be merged into ``develop``.
+
+Branch Names
+++++++++++++++++++++++++++++++++++++++++++++
 The branch naming conventions are as follows:
 
 - **User branch:** ``user/my_user_name/foo_bar`` -- "private" development sandbox per user
 - **Feature branch:** ``feature/foo_bar`` -- shared feature development
 
-**Hint:** Most development will occur in user branches! If multiple users are working on an eMach feature concurrently, use a feature branch.
+**Hint:** Most development will occur in user branches! If multiple developers are working on an eMach feature concurrently, use a feature branch.
 
 Contributors can expect that their user branches will not be commited to by other users---this is "private" space. On the other hand,
 feature branches are "public" space and should be treated as such---at any time, another developer can commit new code onto the branch.
@@ -90,6 +101,8 @@ In conducting the review, the reviewer should perform the following steps:
 4. Closely read of the grammar and syntax of the language to ensure that it reads clearly; if small edits are needed, consider committing them directly on to the branch
 5. Evaluate if the changeset is generally compliant with the eMach architecture
 6. If the reviewer has the necessary expertise, determine if the physics are correct
+7. Confirm that the PR is closing one or more issues and that the issues are scheduled correctly onto the `eMach Release Planner <https://github.com/orgs/Severson-Group/projects/26/views/1>`_.
+8. Confirm that the PR is merging into the correct branch (this should nearly always be ``develop``) based on how the issues are scheduled for release. 
 
 Reviewers are expected to leave feedback directly on files within the changeset and to provide summary review comments. Level 1 reviewers are asked to copy-paste this template into their review:
 
@@ -103,6 +116,9 @@ Reviewers are expected to leave feedback directly on files within the changeset
     - Is the writing, grammar, and syntax correct and clear? [Yes or No]
     - Is the changeset compliant with the eMach architecture? [Yes or No]
     - Does this review consider whether this physics are accurate? [Yes or No]
+    - Are the correct issues being closed (and are there no partially completed issues)? [Yes, or if No: either fix this or give the developer instructions to fix]
+    - Did the reviewer change [the release schedule](https://github.com/orgs/Severson-Group/projects/26/views/1) for the issues bing closed? [If yes, briefly explain why]
+    - Did the reviewer change the branch the PR is being merged into? [If yes, briefly explain why]
     - Is PR approved to Level 2? [Yes or No]
 
 For any answers of "No," please provide an explanation.
@@ -115,7 +131,9 @@ A Level 2 reviewer should be someone with expert understanding of the eMach code
 1. Review the remarks from the Level 1 reviewer and determine if anything from this review requires further investigation
 2. Review whether the approach, code, and documentation is compliant with the eMach architecture
 3. Identify whether the physics are correct (seek outside help as needed, including from the developer)
-4. Request changes/give final approval for merge into ``develop``
+4. Request changes/give final approval for merge.
+5. Finalize the release schedule for the issues being closed on the `eMach Release Planner <https://github.com/orgs/Severson-Group/projects/26/views/1>`_.
+6. Finalize the branch that the PR is being merged into.
 
 Level 2 reviewers are asked to copy-paste this template into their review:
 
@@ -128,7 +146,10 @@ Level 2 reviewers are asked to copy-paste this template into their review:
     - Is the writing, grammar, and syntax correct and clear? [Yes or No]
     - Is the changeset compliant with the eMach architecture? [Yes or No]
     - Are the physics accurate? [Yes or No]
+    - Did the reviewer change [the release schedule](https://github.com/orgs/Severson-Group/projects/26/views/1) for the issues bing closed? [If yes, briefly explain why]
+    - Did the reviewer change the branch the PR is being merged into? [If yes, briefly explain why]
     - Level 1 re-review instructions (if revisions are requested):
+    - When your PR is approved, **remember to merge via `Squash and Merge`**. Please ask if you are unsure of how to do this.
 	
 For any answers of "No," please provide an explanation.
 

diff --git a/docs/source/maintainer.rst b/docs/source/maintainer.rst
@@ -6,7 +6,7 @@ This guide is intended to describe the protocol adopted for the *eMach* code dev
 
 .. tip:: Read about semantic versioning on the main `semver.org <https://semver.org/>`_ website. This greatly helps to explain the concepts below.
 
-
+.. _branches-in-git:
 Branches in git
 -------------------------------------------
 
@@ -43,8 +43,44 @@ A so-called release branch refers to a labeled major and minor release, but unsp
 The naming pattern is: ``vA.B.x`` where ``A`` and ``B`` are numbers and ``x`` denotes any bug fix number.
 For example, the initial release branch is called ``v1.0.x``.
 
+Release Planner
+-------------------------------------------
+
+eMach uses a `GitHub Project Board <https://github.com/orgs/Severson-Group/projects/26/views/1>`_ to track and schedule issues 
+(bug fixes and features) for release. All new issues are automatically added to the project board with a status of ``Backlog``. 
+The eMach development team triages these issues to either ``Future Feature`` or ``Future Bug Fix``. When a PR implements
+code to address any issue, the developer (with help from reviewers) updates the issue's status to the upcoming version of eMach 
+that they believe the issue belongs in. This has implications for when (and into which branch) the PR should be merged. 
+
+Guidelines for scheduling issues into releases are as follows:
+
+1. Issues triaged as ``Future Bug Fix`` should correspond to Bug Fix releases
+2. ``Future Feature`` issues are either Minor or Major releases, depending on if the code is backwards compatible.
+3. Website changes that consist of correcting type-o's or existing code belong in a Bug Fix release while changes that affect the workflow of contributing to eMach belong in a Minor or Major release.
+4. It is preferred to do timely releases (with only 1 or 2 issues) than to do infrequent, large releases.
+
+.. _change-log:
+Change Log 
+------------------------------------------
+A ``./CHANGELOG.md`` file is maintained to document incremental changes in each release of the project. 
+
+Each entry in the change log should have a markdown heading of the version number (``VA.B.x``) followed by
+a bullet list of changes in the style of commit messages based on the issues that are being released. The
+overarching principle is that the list should be understandable and useful to the people who develop the 
+code.
+
+The following rules should be used to draft this message:
+
+1. Keep each bullet brief
+2. Always start each bullet with a verb. Use the same verbs as much as possible. ``Fix`` and ``Add`` should be the most common. ``Rename``, ``Remove``, and ``Extend`` are also acceptable.
+3. Sort the bullets by the first word. Always list ``Fix`` first, then ``Add``.
+4. Ideally, each of the bullets corresponds to an issue/PR. However, often this leads to too repetitive of a list. It is more important that the list be brief, so consolidate issues into a single bullet as makes sense.
+
+See the `AMDC Firmware Project Repository <https://github.com/Severson-Group/AMDC-Firmware/blob/v1.1.x/CHANGELOG.md>`_ for examples of effective changelog entries.
+
+
 Procedure 
-++++++++++++++++++++++++++++++++++++++++++++
+-------------------------------------------
 
 .. tip:: Refer to the diagram above for a graphical representation of how the git branching should work.
 
@@ -53,11 +89,14 @@ The procedure for creating a new release is mostly common for all three types (m
 1. Update code via topic branches which are based on ``develop`` and merge updates into ``develop``
 2. Ensure development has stablized on the ``develop`` branch
 3. Ensure thorough testing of the latest ``develop`` branch code
-4. Create a final commit to ``develop`` where the ``./CHANGELOG.md`` file is updated with documentation about the new release
-
-Now, depending on which type of release, the procedure differs:
-
-
+4. Review the issues scheduled for this release on the `eMach Release Planner <https://github.com/orgs/Severson-Group/projects/26/views/1>`_. Any issues that are not completed should be rescheduled to a future release
+5. Create a label corresponding to the release (``vA.B.x``) and assign this to all issues being released 
+6. Create and merge PR as the final commit to ``develop`` that updates the ``./CHANGELOG.md`` file with documentation about the new release. See :ref:`change-log` for instructions on drafting this. The PR should be named ``Add changelog notes for vA.B.x release``
+7. Depending on which type of release, follow steps in either :ref:`bug-fix` or :ref:`major-minor`
+8. Follow the steps in :ref:`tag-and-release`
+9. For minor or major releases, add a release version to ReadTheDocs by navigating to ``Versions`` and clicking ``Activate`` on the newly created tag ``VA.B.0``.
+
+.. _bug-fix:
 Bug Fix
 ++++++++++++++++++++++++++++++++++++++++++++
 
@@ -72,6 +111,7 @@ Occasionally, a bug might need to be fixed in a previous release branch, but doe
 In this case, do not change ``develop`` -- simply fix the bug where it needs to be fixed.
 This is depicted in the above diagram as the ``hotfix1`` branch.
 
+.. _major-minor:
 Minor or Major
 ++++++++++++++++++++++++++++++++++++++++++++
 For a new minor or major release, a new release branch needs to be created.
@@ -80,12 +120,13 @@ For a new minor or major release, a new release branch needs to be created.
 2. Update GitHub's default repo branch to be the latest release branch which was just created
 3. Update the documentation website to reflect the minor or major breaking changes
 
+.. _tag-and-release:
 Tag and Release
--------------------------------------------
+++++++++++++++++++++++++++++++++++++++++++++
 After following the above steps, the release branch(es) will hold the latest stable code release.
 Users which checkout the release branch will have access to the code.
 
-To complete the release, git tag(s) need to be created and GitHub release(s) need to be created.
+Git tag(s) need to be created and GitHub release(s) need to be created.
 
 1. Create git tag(s) pointing to the merge commit(s) on the release branch(es). If the new code was only merged to one release branch, only one tag will be created. However, if a bug fix was merged to multiple release branches, then the appropriate version number should be used to tag each merge commit.
-2. For each new git tag, create a GitHub Release with the same name as the tag and include a description of the changes per the changelog contents.
+2. For each new git tag, create a GitHub Release with the same name as the tag and include a description of the changes that is identical to the changelog contents.