Merge upstream master

1 files changed, 97 insertions, 23 deletions

diff --git a/RELEASING.txt b/RELEASING.txt
index 87ff62c53..d8572fa94 100644
--- a/RELEASING.txt
+++ b/RELEASING.txt
@@ -1,7 +1,25 @@
 Releasing Pyramid
 =================
 
-- Do any necessary branch merges (e.g. master to branch, branch to master).
+- For clarity, we define releases as follows.
+
+  - 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:
 
@@ -15,28 +33,35 @@ Releasing Pyramid
 
 - Run tests on Windows if feasible.
 
-- Make sure all scaffold tests pass (Py 2.6, 2.7, 3.2, 3.3, 3.4, pypy, and
-  pypy3 on UNIX; this doesn't work on Windows):
+- Make sure all scaffold tests pass (Py 2.7, 3.3, 3.4, 3.5, and pypy on UNIX;
+  this doesn't work on Windows):
 
   $ ./scaffoldtests.sh
 
 - 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
-  changes in CHANGES.txt .
+  changes in CHANGES.txt.
 
-- update README.rst to use correct versions of badges and URLs according to
+- Update README.rst to use correct versions of badges and URLs according to
   each branch and context, i.e., RTD "latest" == GitHub/Travis "1.x-branch".
 
 - Update whatsnew-X.X.rst in docs to point at change log entries for individual
   releases if applicable.
 
-- Change setup.py version to the new version number.
+- For major version releases, in contributing.md, update branch descriptions.
 
-- Change CHANGES.txt heading to reflect the new version number.
+- For major version releases, in docs/conf.py, update values under
+  html_theme_options for in_progress and outdated across master, releasing
+  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 release version number.
 
 - Make sure PyPI long description renders (requires ``collective.dist``
   installed into your Python)::
@@ -45,50 +70,99 @@ Releasing Pyramid
 
 - Create a release tag.
 
-- Make sure your Python has ``setuptools-git``, ``twine`` and ``wheel``
+- Make sure your Python has ``setuptools-git``, ``twine``, and ``wheel``
   installed and release to PyPI::
 
   $ python setup.py sdist bdist_wheel
   $ twine upload dist/pyramid-X.X-*
 
-- Edit Pylons/pylonshq/templates/home/home.mako for minor and major updates.
+- 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. Add heading
+  "unreleased" for the version number.
+
+- From the release branch, forward port the changes in CHANGES.txt to
+  HISTORY.txt.
+
+- In contributing.md, forward port branch descriptions from release branch.
 
-- Edit Pylons/pylonshq/templates/home/inside.rst for major updates only.
+- In docs/conf.py, add a commented line under
+  pylons_sphinx_latesturl_pagename_overrides for the release.
 
-- Edit Pylons/pylonsrtd/pylonsrtd/docs/pyramid.rst for all updates.
+- 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.
+
+- Edit Pylons/trypyramid.com/src/templates/resources.html for major releases
+  only.
+
+- Edit Pylons/pylonsrtd/pylonsrtd/docs/pyramid.rst for major releases only.
 
 - 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
+
+=== One time only for new version, first pre-release ===
+What's New
+http://docs.pylonsproject.org/projects/pyramid/en/1.X-branch/whatsnew-1.X.html
+=== For all subsequent pre-releases ===
+Changes
+http://docs.pylonsproject.org/projects/pyramid/en/1.X-branch/changes.html#version-yyyy-mm-dd
 
-Announcement template
-----------------------
+Issues
+https://github.com/Pylons/pyramid/issues
+```
+
+- Announce to maillist.
 
-Pyramid 1.1.X has been released.
+```
+Pyramid 1.X.X has been released.
 
 Here are the changes:
 
 <<changes>>
 
-A "What's New In Pyramid 1.1" document exists at
-http://docs.pylonsproject.org/projects/pyramid/1.1/whatsnew-1.1.html .
+A "What's New In Pyramid 1.X" document exists at
+http://docs.pylonsproject.org/projects/pyramid/1.X-branch/whatsnew-1.X.html .
 
-You will be able to see the 1.1 release documentation (across all
+You will be able to see the 1.X release documentation (across all
 alphas and betas, as well as when it eventually gets to final release)
-at http://docs.pylonsproject.org/projects/pyramid/1.1/ .
+at http://docs.pylonsproject.org/projects/pyramid/1.X-branch/ .
 
 You can install it via PyPI:
 
-  easy_install Pyramid==1.1a4
+  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
+```