Documentation-update-process.md

@@ -20,19 +20,22 @@ When you save your changes version, GitHub automatically creates a fork (if it d
 
 0. This is part of the [[Release process checklist]].
 1. Clone the repository `git clone https://github.com/mathjax/mathjax-docs.git`
-1. Create a branch `current` corresponding to the **current** version, i.e., the version that will be replaced by the new release.
-1. In the `current` branch, modify
-    * the edit-on-github link `_templates/sourcelink.html` to point to the `current` branch.
-    * the theme layout `_themes/sphinx-bootstrap/layout.html`: add the version-warning to the quick-links:
-        * After `<li><strong>Quick links</strong></li>` insert `<li> <a class="btn btn-mini btn-success" href="http://docs.mathjax.org/">Newer version available!</a> </li>`
-1. Commit & push pack to github: `git commit -a -m "(log message about the 'current' branch)" && 
+1. Merge `master` into the branch `current` corresponding to the **current** version, i.e., the version that will be replaced by the new release.
+1. Push `current` to github: `git commit -a -m "(log message about the 'current' branch)" && 
  git push origin "current"`
-1. Then checkout the `master` branch,
+1. Update `master` with all necessary documentation for the new release; in particular
      * update the version number in the Sphinx configuration file `config.py`.
      * Create a "What's new"-page for the new release.
+     * Note: The `master` branch will always be the most up-to-date, being visible at docs.mathjax.org/en/latest.
+1. Upon release, create `vN.m-latest` branch for the new release and modify it (Note: this branch will have to be updated updated manually but will allow people to have a stable link for documentation of that version)
+    * the edit-on-github link `_templates/sourcelink.html` to point to the `current` branch.
+    * the theme layout `_themes/sphinx-bootstrap/layout.html`: add the version-warning to the quick-links:
+        * After `<li><strong>Quick links</strong></li>` insert `<li> <a class="btn btn-mini btn-success" href="http://docs.mathjax.org/">Newer version available!</a> </li>` (this may seem counter-intuitive, but `latest` is designed to be more up-to-date.
+1. Commit & push pack to github: `git commit -a -m "(log message about the new release branch)" && 
+ git push origin "vN.m-latest"`.
 1. Commit & push pack to github: `git commit -a -m "(log message about version change)" && 
  git push origin master`
-1. Visit the user page on ReadTheDocs and check that `current` branch is included in the build list.
+1. Log into ReadTheDocs and add the `vN.m-latest` branch to the build list.
 
 ### Appendix: Understanding the process