Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 131 insertions, 18 deletions

diff --git a/RELEASING.txt b/RELEASING.txt
index 115edec5f..e50adb52b 100644
--- a/RELEASING.txt
+++ b/RELEASING.txt
@@ -1,51 +1,164 @@
 Releasing Pyramid
 =================
 
-- Make sure all unit tests pass and statement coverage is at 100%::
+- For clarity, we define releases as follows.
 
-  $ python setup.py nosetests --with-coverage
+  - 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.
 
-- Make sure all scaffold tests pass:
+  - A release is final when it is no longer pre-release.
 
-  $ python pyramid/scaffolds/tests.py
+  - 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:
+
+  $ git pull
+
+- Do platform test via tox:
+
+  $ tox -r
+
+  Make sure statement coverage is at 100% (the test run will fail if not).
+
+- Run tests on Windows if feasible.
+
+- Make sure all scaffold tests pass (Py 2.7, 3.3, 3.4, 3.5, pypy, and pypy3 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).
 
-- Copy relevant changes (delta bug fixes) from CHANGES.txt to
-  docs/whatsnew-X.X.
+- Change CHANGES.txt heading to reflect the new version number.
 
-- Make sure docs render OK::
+- 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.
 
-  $ cd docs
-  $ make clean html
+- 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".
 
-  There should be no meaningful errors or warnings.
+- 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 docs/conf.py version to 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 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)::
 
-  $ python setup.py check --restructuredtext
+  $ python setup.py check -r
 
 - Create a release tag.
 
-- Release to PyPI::
+- 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-*
+
+- 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.
 
-  $ python setup.py sdist register upload
+- 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.
+
+- 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.
+
+```
+Pyramid 1.x released.
+
+PyPI
+https://pypi.python.org/pypi/pyramid/1.x
+
+What's New
+http://docs.pylonsproject.org/projects/pyramid/1.X/whatsnew-1.X.html
+
+Issues
+https://github.com/Pylons/pyramid/issues
+```
 
 - Announce to maillist.
 
-- Announce to Twitter.
+```
+Pyramid 1.X.X has been released.
+
+Here are the changes:
+
+<<changes>>
+
+A "What's New In Pyramid 1.X" document exists at
+http://docs.pylonsproject.org/projects/pyramid/1.X/whatsnew-1.X.html .
+
+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.X/ .
+
+You can install it via PyPI:
+
+  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!
 
+- Pyramid core developers
+```