update RELEASING.txt to better account for master and previous branches

- add term "final" release
- explicitify the implicit
-

1 files changed, 58 insertions, 11 deletions

diff --git a/RELEASING.txt b/RELEASING.txt
index 866fff305..8b3d908e6 100644
--- a/RELEASING.txt
+++ b/RELEASING.txt
@@ -6,12 +6,19 @@ Releasing Pyramid
   - Alpha, beta, dev and similar statuses do not qualify whether a release is
     major or minor. The term "pre-release" means alpha, beta, or dev.
 
+  - A release is final when it is no longer pre-release.
+
   - A *major* release is where the first number either before or after the
     first dot increases. Examples: 1.6 to 1.7a1, or 1.8 to 2.0.
 
   - A *minor* or *bug fix* release is where the number after the second dot
     increases. Example: 1.6 to 1.6.1.
 
+Prepare new release branch
+--------------------------
+
+- Create a new release branch, incrementing the version number.
+
 - Do any necessary branch merges (e.g., master to branch, branch to master).
 
 - On release branch:
@@ -34,6 +41,8 @@ Releasing Pyramid
 - Ensure all features of the release are documented (audit CHANGES.txt or
   communicate with contributors).
 
+- Change CHANGES.txt heading to reflect the new version number.
+
 - Copy relevant changes (delta bug fixes) from CHANGES.txt to
   docs/whatsnew-X.X (if it's a major release).  Minor releases should
   include a link under "Bug Fix Releases" to the minor feature
@@ -52,10 +61,7 @@ Releasing Pyramid
   branch, and previously released branch. Also in the previously released
   branch only, uncomment the sections to enable pylons_sphinx_latesturl.
 
-- Change setup.py version to the new version number on both master and the new
-  branch.
-
-- Change CHANGES.txt heading to reflect the new version number.
+- Change setup.py version to the release version number.
 
 - Make sure PyPI long description renders (requires ``collective.dist``
   installed into your Python)::
@@ -70,6 +76,37 @@ Releasing Pyramid
   $ python setup.py sdist bdist_wheel
   $ twine upload dist/pyramid-X.X-*
 
+- Configure RTD to publish the new release version of the docs.
+
+Prepare master for further development (major releases only)
+------------------------------------------------------------
+
+- Checkout master.
+
+- In CHANGES.txt, preserve headings but clear out content.
+
+- From the release branch, forward port the changes in CHANGES.txt to
+  HISTORY.txt.
+
+- In contributing.md, forward port branch descriptions from release branch.
+
+- In docs/conf.py, add a commented line under
+  pylons_sphinx_latesturl_pagename_overrides for the release.
+
+- Change setup.py version to the next version number.
+
+Update previous version (final releases only)
+---------------------------------------------
+
+- In docs/conf.py, update values under html_theme_options for in_progress and
+  outdated. Uncomment the sections to enable pylons_sphinx_latesturl.
+
+- Configure RTD to point the "latest" alias to the new release version of the
+  docs.
+
+Marketing and communications
+----------------------------
+
 - Edit Pylons/pylonshq/templates/home/home.mako.
 
 - Edit Pylons/pylonshq/templates/home/inside.rst for major releases only.
@@ -82,15 +119,24 @@ Releasing Pyramid
 - Edit `http://wiki.python.org/moin/WebFrameworks
   <http://wiki.python.org/moin/WebFrameworks>`_.
 
-- Publish new version of docs.
+- Announce to Twitter.
 
-- Announce to maillist.
+```
+Pyramid 1.x released.
 
-- Announce to Twitter.
+PyPI
+https://pypi.python.org/pypi/pyramid/1.x
+
+What's New
+http://docs.pylonsproject.org/projects/pyramid/1.X/whatsnew-1.X.html
 
-Announcement template
-----------------------
+Issues
+https://github.com/Pylons/pyramid/issues
+```
+
+- Announce to maillist.
 
+```
 Pyramid 1.X.X has been released.
 
 Here are the changes:
@@ -106,11 +152,12 @@ at http://docs.pylonsproject.org/projects/pyramid/1.X/ .
 
 You can install it via PyPI:
 
-  easy_install Pyramid==1.X
+  pip install Pyramid==1.X
 
 Enjoy, and please report any issues you find to the issue tracker at
 https://github.com/Pylons/pyramid/issues
 
 Thanks!
 
-- C
+- Pyramid core developers
+```