RELEASING.txt 5.76 KB
Newer Older
1 2 3
Releasing Pyramid
=================

4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
- 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).
23 24 25 26

- On release branch:

  $ git pull
27 28 29

- Do platform test via tox:

30
  $ tox -r
31

32
  Make sure statement coverage is at 100% (the test run will fail if not).
33

34
- Run tests on Windows if feasible.
35

36 37
- Make sure all scaffold tests pass (CPython 2.7, 3.4, 3.5, 3.6, and 3.7, and
  PyPy on UNIX; this doesn't work on Windows):
38

39
  $ tox -e{py27,py34,py35,py36,py37,pypy}-scaffolds
40

41 42 43 44 45 46 47 48
- For each ``pyramid-cookiecutter-*``, make a new branch off "master" with the
  same name to align with the new Pyramid release branch name.

- In the docs, update the ``cookiecutter`` command with the new branch name,
  for example, ``cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout
  x.y-branch``. A search for ``cookiecutter gh:Pylons/pyramid-cookiecutter-``
  should return all instances to be updated.

49
- Ensure all features of the release are documented (audit CHANGES.rst or
50 51
  communicate with contributors).

52
- Change CHANGES.rst heading to reflect the new version number.
53

54
- Copy relevant changes (delta bug fixes) from CHANGES.rst to
55 56
  docs/whatsnew-X.X (if it's a major release).  Minor releases should
  include a link under "Bug Fix Releases" to the minor feature
57
  changes in CHANGES.rst.
58

59 60
- Update README.rst to use correct versions of badges, URLs, and ALT option
  according to the new release branch name.
61 62 63 64

- Update whatsnew-X.X.rst in docs to point at change log entries for individual
  releases if applicable.

65
- For major version releases, in contributing.md, update branch descriptions.
66

67 68 69 70 71 72
- 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.
73

74
- Make sure PyPI long description renders::
75

76
  $ tox -e lint
77 78 79

- Create a release tag.

80 81 82 83 84 85 86
  $ git tag X.X

- Build the sdist and wheel.

  $ tox -e build

- Upload the artifacts to PyPI:
87

88
  $ twine upload dist/pyramid-X.X-*
89

90 91 92 93 94 95 96
- Configure RTD to publish the new release version of the docs.

Prepare master for further development (major releases only)
------------------------------------------------------------

- Checkout master.

97
- In CHANGES.rst, preserve headings but clear out content. Add heading
98 99
  "unreleased" for the version number.

100 101
- From the release branch, forward port the changes in CHANGES.rst to
  HISTORY.rst.
102 103 104 105 106 107 108 109

- 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.

110 111 112 113 114 115 116 117
- Update README.rst to use correct versions of badges, URLs, and ALT option
  for "master" instead of the major release version.

- In the docs, update the ``cookiecutter`` command with ``master``,
  for example, ``cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout
  master``. A search for ``cookiecutter gh:Pylons/pyramid-cookiecutter-``
  should return all instances to be updated.

118 119 120 121 122 123 124 125 126 127
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.


128 129
Cookiecutters
-------------
130

131
- For each cookiecutter, clone the newly released branch to "latest" branch.
132 133


134 135 136 137 138
Marketing and communications
----------------------------

- Edit Pylons/trypyramid.com/src/templates/resources.html for major releases,
  pre-releases, and once pre-releases are final.
139

140 141
- Edit `https://wiki.python.org/moin/WebFrameworks
  <https://wiki.python.org/moin/WebFrameworks>`_.
142

143 144
- Edit `https://en.wikipedia.org/wiki/Pylons_project <https://en.wikipedia.org/wiki/Pylons_project>`_.

145 146
- Edit `https://en.wikipedia.org/wiki/Comparison_of_web_frameworks <https://en.wikipedia.org/wiki/Comparison_of_web_frameworks>`_.

147
- Announce to Twitter.
148

149 150
```
Pyramid 1.x released.
151

152
PyPI
153
https://pypi.org/project/pyramid/1.x/
154

155 156
=== One time only for new version, first pre-release ===
What's New
157
https://docs.pylonsproject.org/projects/pyramid/en/1.X-branch/whatsnew-1.X.html
158 159
=== For all subsequent pre-releases ===
Changes
160
https://docs.pylonsproject.org/projects/pyramid/en/1.X-branch/changes.html#version-yyyy-mm-dd
161 162 163 164 165 166

Issues
https://github.com/Pylons/pyramid/issues
```

- Announce to maillist.
167

168
```
169
Pyramid 1.X.X has been released.
170

171 172
The full changelog is here:
https://docs.pylonsproject.org/projects/pyramid/en/1.X-branch/changes.html
173

174
What's New In Pyramid 1.X:
175
https://docs.pylonsproject.org/projects/pyramid/en/1.X-branch/whatsnew-1.X.html
176

177 178
1.X release documentation (across all alphas and betas, as well as when it gets
to final release):
179
https://docs.pylonsproject.org/projects/pyramid/en/1.X-branch/
180 181 182

You can install it via PyPI:

183
  pip install Pyramid==1.X
184 185 186 187 188

Enjoy, and please report any issues you find to the issue tracker at
https://github.com/Pylons/pyramid/issues

Thanks!
189

190 191
- Pyramid core developers
```