docs: Infrastructure updates, add howto for making a release (#1304)

This PR: 1. Switches to MyST from recommonmark + m2r. The latter are deprecated and MyST should be an improvement all around (directives possible in markdown now) 2. Adds a navigation point for the existing top level how-to pages 3. Adds a how-to for making a release
acts-project · Jul 8, 2022 · 0f44907 · 0f44907
1 parent 0955220
commit 0f44907
Show file tree

Hide file tree

Showing 10 changed files with 145 additions and 36 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,9 +4,6 @@
 import sys
 import subprocess
 
-from m2r import MdInclude
-from recommonmark.transform import AutoStructify
-
 # check if we are running on readthedocs.org
 on_readthedocs = os.environ.get("READTHEDOCS", None) == "True"
 
@@ -22,7 +19,7 @@
 
 extensions = [
     "breathe",
-    "recommonmark",
+    "myst_parser",
     "sphinx.ext.mathjax",
     "sphinx_markdown_tables",
 ]
@@ -41,6 +38,8 @@
 smartquotes = True
 numfig = True
 
+myst_enable_extensions = ["dollarmath"]
+
 # -- Options for HTML output --------------------------------------------------
 
 # ensure we use the RTD them when building locally
@@ -116,18 +115,4 @@
 
 
 def setup(app):
-    app.add_config_value(
-        "recommonmark_config",
-        {
-            "enable_math": True,
-            "enable_inline_math": True,
-        },
-        True,
-    )
-    app.add_transform(AutoStructify)
-
-    app.add_config_value("no_underscore_emphasis", False, "env")
-    app.add_config_value("m2r_parse_relative_links", False, "env")
-    app.add_config_value("m2r_anonymous_references", False, "env")
-    app.add_config_value("m2r_disable_inline_math", False, "env")
-    app.add_directive("mdinclude", MdInclude)
+    pass
diff --git a/docs/figures/release/milestone_drop.png b/docs/figures/release/milestone_drop.png
diff --git a/docs/figures/release/milestones.png b/docs/figures/release/milestones.png
diff --git a/docs/figures/release/next_milestone.png b/docs/figures/release/next_milestone.png
diff --git a/docs/figures/release/select_all_closed.png b/docs/figures/release/select_all_closed.png
diff --git a/docs/howto/howto.rst b/docs/howto/howto.rst
@@ -0,0 +1,10 @@
+How-to guides
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   profiling
+   smearing_digitization_config
+   release
+
diff --git a/docs/howto/release.md b/docs/howto/release.md
@@ -0,0 +1,101 @@
+# How to make a release
+
+We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) for all of our PRs. We use the common prefixes: `fix:`, `feat:`, `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`.
+
+The next version number for a release is automatically determined from the PRs (commits) that have been merged since the last release, following semantic versioning. On top of that, release notes are automatically generated from the PR titles, using the prefixes as groups.
+
+## Step 1: Update the release branch
+
+```{note}
+This assumes you have a local clone of the ACTS repository at hand.
+You'll also need write permissions on the upstream ACTS repository to be able to push to the `releases` branch.
+```
+
+
+```console
+$ git checkout releases
+$ git fetch upstream # make sure you're up to date
+$ git merge --no-ff upstream/main
+```
+
+At this point, your commit graph should look something like this:
+
+```
+de4bffa 2022-06-23 11:02 +0200 Paul Gessinger             M─┐ [releases] Merge remote-tracking branch 'origin/main' into releases
+75f0835 2022-06-22 19:27 +0200 Andreas Stefl              │ o fix: SimulationActor produces negative MaterialSlab thickness (#1288)
+c586094 2022-06-22 18:41 +0200 Andreas Stefl              │ o refactor: python examples vertex_fitting.py (#1286)
+e6e7949 2022-06-22 10:31 +0200 Paul Gessinger             │ o ci: Bump ccache max size to 500MB (#1285)
+bf8cb1c 2022-06-21 11:26 -0400 Joe Osborn                 │ o {fork/main} refactor: Move propagator options to general fitter options (#1282)
+7bf3981 2022-06-20 20:16 +0100 Scott Hurley               │ o feat: Add Profiling Support with gperftools (#1274)
+4a21df3 2022-06-14 18:32 +0200 Paul Gessinger             │ o fix: Add another compat fix for clang+libstdc++ (#1269)
+93c608d 2022-06-14 16:35 +0200 Paul Gessinger             │ o ci: Retry nodeps build if it fails the first time (#1283)
+9920a81 2022-06-14 14:53 +0200 Paul Gessinger             │ o ci: Reduce ccache limit to 150MB (#1270)
+baa4222 2022-06-14 10:16 +0200 Benjamin Huth              │ o fix: Add missing dependency in Exa.TrkX plugin (#1276)
+adf079e 2022-06-08 12:47 +0000 github-actions[bot]        o │ <v19.2.0> Bump to version v19.2.0
+4ee53fd 2022-06-08 14:46 +0200 Paul Gessinger             M─│─┐ Merge branch main into releases
+f9a0979 2022-06-08 09:35 +0200 Noemi Calace               │ o─┘ feat: Allow passing seed quality to seeds (#1268)
+8a2260b 2022-06-07 16:31 +0200 Alexander J. Pfleger       │ o feat: RKN-monitoring to AtlasStepper, change type int->size_t (#1264)
+bd55ecb 2022-06-07 15:25 +0200 Noemi Calace               │ o feat: configurable phi values in grid construction (#1275)
+29f3649 2022-06-07 14:22 +0200 Noemi Calace               │ o fix: Fixing typo in name of variable and associated methods (#1277)
+239ece3 2022-06-03 17:39 +0200 robertlangenberg           │ o  bump macos dependencies (#1279)
+f77f377 2022-05-30 15:46 +0200 Noemi Calace               │ o feat: Adding features for sorting space points in r in (phi, z) grid (#1267)
+a7ee09d 2022-05-25 11:17 +0200 Luis Falda Coelho          │ o fix: Bug in xyz strip coordinates transformation  (#1265)
+82f42a2 2022-05-25 09:02 +0000 github-actions[bot]        o │ <v19.1.0> Bump to version v19.1.0
+7c59e12 2022-05-25 10:26 +0200 Paul Gessinger             M─│─┐ Merge remote-tracking branch 'origin/main' into releases
+4ceddf3 2022-05-25 10:26 +0200 Luis Falda Coelho          │ o─┘ feat: ITk seedFilter integration and seed quality confirmation  (#1201)
+```
+
+You can now push the updated `releases` branch to the remote `releases` branch using `git push -u upstream releases`. 
+
+On push, a CI job should run and create an additional commit on the `releases` branch, which bumps a number of version numbers. That commit is going to be the one tagged with the correct version. It doesn't hurt to make sure that commit looks right, as in it bumps to a sensible next version number.
+
+
+## Step 2: Prepare milestone
+
+By convention, we assign all open PRs and issues to the `next` milestone. When a new release is cut, all closed issues and PRs are moved over to a dedicated milestone named after the next version number. To do this, go to the *Pull Requests* view on the main repository, and click *Milestones*:
+
+```{image} /figures/release/milestones.png
+---
+width: 300px
+alt: The milestones button
+---
+```
+
+First, create a new milestone here. Name it `vX.Y.Z`, corresponding to the next version (you can check the release CI job mentioned above to determine this. The job will also create an unreleased GitHub *release* which should have the right name).
+
+Next, go back to the list of milestones and go to the `next` milestone, and click on *closed* to get to a list of all closed PRs and issues assigned to it:
+
+```{image} /figures/release/next_milestone.png
+---
+alt: The next milestone, which has a "closed" button
+---
+```
+
+You'll be taken to a list view which shows all closed PRs and issues assigned to the `next` milestone. On the top left there should be a checkbox allowing you to select all visible items:
+
+```{image} /figures/release/select_all_closed.png
+---
+alt: Checkbox to select all visible PRs and issues.
+width: 200px
+---
+```
+
+```{note} The checkbox will only select the items on the visible page. If there are many items, it's possible you'll have to redo this step until it has been applied to all items.
+```
+
+Towards the right there's a button called *Milestone* which allows you to select a milestone to assign. Assign all closed items to the new milestone you created above.
+
+```{image} /figures/release/milestone_drop.png
+---
+alt: Dropdown to assign the selected items to a new milestone
+width: 300px
+---
+```
+
+## Step 3: Publish release
+
+The release CI job should have created a draft release visible in the GitHub interface. If you navigate to the list of all releases, there should be an entry for this new release. You should
+
+1. Inspect the auto-generated release note, and see if there are any obvious mistakes here that the job might have made.
+2. Check that the target commit hash, that the release will generate a tag for once published, actually corresponds to the commit on the `releases` branch that the CI job from before created.
+3. Click the *Publish* button to create the release.
diff --git a/docs/index.rst b/docs/index.rst
@@ -32,6 +32,7 @@ Key features:
    formats/formats
    api/api
    contributionguide
+   howto/howto
    codeguide
    authors
    license
diff --git a/docs/requirements.in b/docs/requirements.in
@@ -1,7 +1,7 @@
 breathe==4.31.0
 exhale==0.2.3
 m2r==0.2.1
-recommonmark==0.7.1
+myst-parser
 sphinx==4.2.0
 sphinx_markdown_tables==0.0.15
 sphinx_rtd_theme==0.5.2
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with python 3.9
 # To update, run:
 #
-#    pip-compile docs/requirements.in
+#    pip-compile ../docs/requirements.in
 #
 alabaster==0.7.12
     # via sphinx
@@ -12,41 +12,51 @@ beautifulsoup4==4.9.3
     # via bs4
 breathe==4.31.0
     # via
-    #   -r docs/requirements.in
+    #   -r ../docs/requirements.in
     #   exhale
 bs4==0.0.1
     # via exhale
 certifi==2021.5.30
     # via requests
 chardet==4.0.0
     # via requests
-commonmark==0.9.1
-    # via recommonmark
 docutils==0.16
     # via
     #   breathe
     #   m2r
-    #   recommonmark
+    #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
 exhale==0.2.3
-    # via -r docs/requirements.in
+    # via -r ../docs/requirements.in
 idna==2.10
     # via requests
 imagesize==1.2.0
     # via sphinx
 jinja2==3.0.1
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 lxml==4.6.3
     # via exhale
 m2r==0.2.1
-    # via -r docs/requirements.in
+    # via -r ../docs/requirements.in
 markdown==3.3.4
     # via sphinx-markdown-tables
+markdown-it-py==2.1.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==2.0.1
     # via jinja2
+mdit-py-plugins==0.3.0
+    # via myst-parser
+mdurl==0.1.1
+    # via markdown-it-py
 mistune==0.8.4
     # via m2r
+myst-parser==0.18.0
+    # via -r ../docs/requirements.in
 packaging==21.0
     # via sphinx
 pygments==2.9.0
@@ -55,8 +65,8 @@ pyparsing==2.4.7
     # via packaging
 pytz==2021.1
     # via babel
-recommonmark==0.7.1
-    # via -r docs/requirements.in
+pyyaml==6.0
+    # via myst-parser
 requests==2.25.1
     # via sphinx
 six==1.16.0
@@ -67,15 +77,15 @@ soupsieve==2.2.1
     # via beautifulsoup4
 sphinx==4.2.0
     # via
-    #   -r docs/requirements.in
+    #   -r ../docs/requirements.in
     #   breathe
     #   exhale
-    #   recommonmark
+    #   myst-parser
     #   sphinx-rtd-theme
-sphinx_markdown_tables==0.0.15
-    # via -r docs/requirements.in
-sphinx_rtd_theme==0.5.2
-    # via -r docs/requirements.in
+sphinx-markdown-tables==0.0.15
+    # via -r ../docs/requirements.in
+sphinx-rtd-theme==0.5.2
+    # via -r ../docs/requirements.in
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
@@ -88,6 +98,8 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
+typing-extensions==4.3.0
+    # via myst-parser
 urllib3==1.26.6
     # via requests