Merge pull request #257 from bourque/update-release-workflow

Update release workflow to reflect use of 'version' branches

docs/source/development/release-workflow.rst

@@ -9,13 +9,13 @@ repositories, and the steps needed to push said software to the production envir
 Software Releases
 ^^^^^^^^^^^^^^^^^
 
-Any changes merged or pushed to the ``main`` branch should follow a specific release workflow which follows the diagram
-shown in the :ref:`git & GitHub Workflow <git-and-github-workflow>` page. This includes both 'nominal releases' (i.e.
-new features being merged into ``main``) and 'hotfixes' (i.e. bug fixes made directly to ``main``). These workflows are
-described below. It is assumed that steps (1) through (4) in the :ref:`git & GitHub Workflow <git-and-github-workflow>`
-are already completed.
+This project uses a workflow in which releases are made off of a 'version branch' (e.g. ``v0.1.x``), as depicted in the
+diagram shown in the :ref:`git & GitHub Workflow <git-and-github-workflow>` page. This includes both 'nominal releases'
+(i.e. new features to be released to the public) and 'patches' (i.e. bug fixes to the version branch). These workflows
+are described below. It is assumed that steps (1) through (4) in the
+:ref:`git & GitHub Workflow <git-and-github-workflow>` are already completed.
 
-*Note: We use the 'imap_processing' repository as an example here, but this can be applied to 'sds-data-manager' as
+*Note: We use the ``imap_processing`` repository as an example here, but this can be applied to ``sds-data-manager`` as
 well.*
 
 
@@ -26,38 +26,38 @@ Nominal releases
 
 #. Make sure the ``dev`` branch is up-to-date with any changes you want included in the release (i.e. merge in any
    feature branches using the nominal :ref:`git & GitHub Workflow <git-and-github-workflow>`).
-#. Create a new 'release' branch off of ``dev``.  The name of the branch should match the version number to be used for
-   the release, which should follow the :ref:`software versioning <versioning>` conventions.
-#. Make any release-specific commits to the new release branch using the nominal ``git add``/``git commit`` cycle. This
+#. Create a new version branch off of ``dev``.  The name of the branch should match the version number to be used for
+   the release, which should follow the :ref:`software versioning <versioning>` conventions. The patch number should be
+   marked with a ``x``, and the name should be prepended with ``v`` (e.g. ``v0.1.x``).
+#. Make any release-specific commits to the new version branch using the nominal ``git add``/``git commit`` cycle. This
    may include commits that add release notes, or update version numbers in various configurations.
-#. Push the release branch to the main ``IMAP-Science-Operations-Center`` ``imap_processing`` repo (i.e. ``upstream``).
-#. In GitHub, create two pull requests: one that merges the release branch into ``main``, and one that merges the
-   release branch into ``dev``. Proceed with the nominal review & merge process described in steps (10) and (11) in the
-   :ref:`git & GitHub Workflow <git-and-github-workflow>` section.
-#. Once the changes are merged into the ``main`` branch, create a `new release
-   <https://github.com/IMAP-Science-Operations-Center/imap_processing/releases>`_ for the merge commit and assign the
-   appropriate version number.
-
-
-.. _Making-hotfixes:
-
-Making hotfixes
-"""""""""""""""
-
-*Note: A hotfix should generally be avoided unless there is some specific reason to bypass the nominal ``dev`` branch
-workflow; for example, if a bug fix is very time critical.*
-
-#. Create a new branch named ``hotfix-<description>`` off of the ``main`` branch, and commit any necessary changes
-   following the nominal ``git add``/``git commit`` cycle.
-#. Push the hotfix branch to the main ``IMAP-Science-Operations-Center`` ``imap_processing`` repo (i.e. ``upstream``),
-   and open two separate pull requests: one that merges the hotfix branch into the ``main`` branch, and one that merges
-   the hotfix branch into the ``dev`` branch.
-#. For each of these pull requests, proceed with the nominal review & merge process described in steps (10) and (11) in
-   the :ref:`git & GitHub Workflow <git-and-github-workflow>`.
-#. Once the changes are merged into the ``main`` branch, create a `new release
-   <https://github.com/IMAP-Science-Operations-Center/imap_processing/releases>`_ or a `new tag
-   <https://github.com/IMAP-Science-Operations-Center/imap_processing/tags>`_ for the merge commit and assign the
-   appropriate :ref:`version number <versioning>`.
+#. Push the version branch to the main ``IMAP-Science-Operations-Center`` ``imap_processing`` repo (i.e. ``upstream``).
+#. Create a `new release <https://github.com/IMAP-Science-Operations-Center/imap_processing/releases>`_, using the
+   version branch as the ``Target`` branch. Assign a new tag with the specific version number, including the patch
+   number (e.g. ``v0.1.0``).
+#. In GitHub, create a pull request that merges the version branch into ``dev``. Proceed with the nominal review & merge
+   process described in steps (10) and (11) in the :ref:`git & GitHub Workflow <git-and-github-workflow>` section.
+
+
+.. _patches:
+
+Patches
+"""""""
+
+This workflow assumes that a version branch has already been created (and released at least once) for the minor version
+which you want to patch (e.g. ``v0.1.x``).
+
+#. Create a new branch off of the version branch that you want to patch (hereby called the 'bug-fix branch'). Commit any
+   relevant bug fixes to this bug-fix branch using the nominal ``git add``/``git commit`` cycle.
+#. Create a new pull request that merges the bug-fix branch into the version branch. Proceed with the nominal review &
+   merge process described in steps (10) and (11) in the :ref:`git & GitHub Workflow <git-and-github-workflow>` section.
+#. Once the changes are merged into the version branch, create a `new release
+   <https://github.com/IMAP-Science-Operations-Center/imap_processing/releases>`_, using the version branch as the
+   ``Target`` branch. Assign a new tag with the specific version number that increases the patch number by one from the
+   most recent tag (e.g. ``v0.1.1``).
+#. In GitHub, create a pull request that merges the version branch into ``dev``. Proceed with the nominal review & merge
+   process described in steps (10) and (11) in the :ref:`git & GitHub Workflow <git-and-github-workflow>` section.
+
 
 
 Deployment

docs/source/development/style-guide/git-and-github-workflow.rst

@@ -6,13 +6,12 @@ git and GitHub Workflow
 The best method for contributing software to the repository is a workflow that involves forking the repository,
 developing changes on "feature" branches, and opening pull requests through GitHub.
 
-The following diagram depicts this workflow (credit to `Atlassian
-<https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`_):
+The following diagram depicts this workflow:
 
-.. image:: https://wac-cdn.atlassian.com/dam/jcr:cc0b526e-adb7-4d45-874e-9bcea9898b4a/04%20Hotfix%20branches.svg?cdnVersion=1089
+.. image:: ../../_static/git-workflow.png
    :alt: git and GitHub Workflow
-   :width: 650
-   :height: 650
+   :width: 700
+   :height: 550
 
 As such, all feature branches should be branched off of and merged back into the ``dev`` branch.