##// END OF EJS Templates
Update release instruction...
Matthias Bussonnier -
Show More
@@ -1,43 +1,39 b''
1 1 IPython Documentation
2 2 ---------------------
3 3
4 4 This directory contains the majority of the documentation for IPython.
5 5
6 6 Deploy docs
7 7 -----------
8 8
9 Run ``make gh-pages``, and follow instruction, that is to say:
10 cd into ``gh-pages``, check that everything is alright and push.
11
9 Documentation is automatically deployed on ReadTheDocs on every push or merged
10 Pull requests.
12 11
13 12
14 13 Requirements
15 14 ------------
16 15 The following tools are needed to build the documentation:
17 16
18 sphinx jsdoc
17 - sphinx
19 18
20 19 On Debian-based systems, you should be able to run::
21 20
22 sudo apt-get install python-sphinx npm
23 sudo npm install -g jsdoc@"<=3.3.0"
21 sudo apt-get install python-sphinx
24 22
25 23 The documentation gets built using ``make``, and comes in several flavors.
26 24
27 ``make html`` - build the API (both Javascript and Python) and narrative
28 documentation web pages, this is the the default ``make`` target, so
29 running just ``make`` is equivalent to ``make html``.
25 ``make html`` - build the API and narrative documentation web pages, this is
26 the default ``make`` target, so running just ``make`` is equivalent to ``make
27 html``.
30 28
31 ``make html_noapi`` - same as above, but without running the auto-generated
32 API docs. When you are working on the narrative documentation, the most time
29 ``make html_noapi`` - same as above, but without running the auto-generated API
30 docs. When you are working on the narrative documentation, the most time
33 31 consuming portion of the build process is the processing and rending of the
34 32 API documentation. This build target skips that.
35 33
36 ``make jsapi`` - build Javascript auto-generated API documents.
37
38 34 ``make pdf`` will compile a pdf from the documentation.
39 35
40 36 You can run ``make help`` to see information on all possible make targets.
41 37
42 38
43 39
@@ -1,193 +1,221 b''
1 1 .. _release_process:
2 2
3 3 =======================
4 4 IPython release process
5 5 =======================
6 6
7 7 This document contains the process that is used to create an IPython release.
8 8
9 9 Conveniently, the `release` script in the `tools` directory of the `IPython`
10 10 repository automates most of the release process. This document serves as a
11 11 handy reminder and checklist for the release manager.
12 12
13 13 1. Set Environment variables
14 14 ----------------------------
15 15
16 16 Set environment variables to document previous release tag, current
17 release milestone, current release version, and git tag::
18
19 PREV_RELEASE=4.0.0
20 MILESTONE=4.1
21 VERSION=4.1.0
22 BRANCH=master
17 release milestone, current release version, and git tag.
23 18
24 19 These variables may be used later to copy/paste as answers to the script
25 20 questions instead of typing the appropriate command when the time comes. These
26 21 variables are not used by the scripts directly; therefore, there is no need to
27 `export` the variables.
22 `export` the variables. Use the following in bash:
23
24 PREV_RELEASE=4.2.1
25 MILESTONE=5.0
26 VERSION=5.0.0
27 BRANCH=master
28
28 29
29 30 2. Create GitHub stats and finish release note
30 31 ----------------------------------------------
31 32
32 33 .. note::
33 34
34 Before generating the GitHub stats, verify that all closed issues and
35 pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
36 `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
35 This step is optional if making a Beta or RC release.
36
37 .. note::
38
39 Before generating the GitHub stats, verify that all closed issues and pull
40 requests have `appropriate milestones
41 <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
42 `This search
43 <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
37 44 should return no results before creating the GitHub stats.
38 45
39 46 If a major release:
40 47
41 48 - merge any pull request notes into what's new::
42 49
43 50 python tools/update_whatsnew.py
44 51
45 - update `docs/source/whatsnew/development.rst`, to ensure it covers
52 - update ``docs/source/whatsnew/development.rst``, to ensure it covers
46 53 the major release features
47 - move the contents of `development.rst` to `versionX.rst` where `X` is
54
55 - move the contents of ``development.rst`` to ``versionX.rst`` where `X` is
48 56 the numerical release version
57
49 58 - generate summary of GitHub contributions, which can be done with::
50 59
51 60 python tools/github_stats.py --milestone $MILESTONE > stats.rst
52 61
53 which may need some manual cleanup of `stats.rst`. Add the cleaned
54 `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where
55 `X` is the numerical release version. If creating a major release, make
56 a new `github-stats-X.rst` file; if creating a minor release, the
57 content from `stats.rst` may simply be added to the top of an existing
58 `github-stats-X.rst` file.
62 which may need some manual cleanup of ``stats.rst``. Add the cleaned
63 ``stats.rst`` results to ``docs/source/whatsnew/github-stats-X.rst``
64 where `X` is the numerical release version. If creating a major release,
65 make a new ``github-stats-X.rst`` file; if creating a minor release, the
66 content from ``stats.rst`` may simply be added to the top of an existing
67 ``github-stats-X.rst`` file.
59 68
60 69 To find duplicates and update `.mailmap`, use::
61 70
62 71 git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
63 72
64 73 3. Make sure the repository is clean
65 74 ------------------------------------
66 75
67 76 of any file that could be problematic.
68 77 Remove all non-tracked files with:
69 78
70 79 .. code::
71 80
72 81 git clean -xfdi
73 82
74 83 This will ask for confirmation before removing all untracked files. Make
75 84 sure the ``dist/`` folder is clean to avoid any stale builds from
76 85 previous build attempts.
77 86
78 87
79 88 4. Update the release version number
80 89 ------------------------------------
81 90
82 Edit `IPython/core/release.py` to have the current version.
91 Edit ``IPython/core/release.py`` to have the current version.
83 92
84 93 in particular, update version number and ``_version_extra`` content in
85 94 ``IPython/core/release.py``.
86 95
87 Make sure the version number matches pep440, in particular, `rc` and `beta` are
88 not separated by `.` or the `sdist` and `bdist` will appear as different
89 releases. For example, a valid version number for a release candidate (rc)
90 release is: ``1.3rc1``. Notice that there is no separator between the '3' and
91 the 'r'. Check the environment variable `$VERSION` as well.
96 Step 5 will validate your changes automatically, but you might still want to
97 make sure the version number matches pep440.
92 98
99 In particular, ``rc`` and ``beta`` are not separated by ``.`` or the ``sdist``
100 and ``bdist`` will appear as different releases. For example, a valid version
101 number for a release candidate (rc) release is: ``1.3rc1``. Notice that there
102 is no separator between the '3' and the 'r'. Check the environment variable
103 ``$VERSION`` as well.
93 104
94 Comment remove the `development` entry in `whatsnew/index.rst`. TODO, figure
105 You will likely just have to modify/comment/uncomment one of the lines setting
106 ``_version_extra``
107
108
109 Comment remove the ``development`` entry in ``whatsnew/index.rst``. TODO, figure
95 110 out how to make that automatic.
96 111
97 112 5. Run the `tools/build_release` script
98 113 ---------------------------------------
99 114
100 Running `tools/build_release` does all the file checking and building that
115 Running ``tools/build_release`` does all the file checking and building that
101 116 the real release script will do. This makes test installations, checks that
102 117 the build procedure runs OK, and tests other steps in the release process.
103 118
104 The `build_release` script will in particular verify that the version number
119 The ``build_release`` script will in particular verify that the version number
105 120 match PEP 440, in order to avoid surprise at the time of build upload.
106 121
107 122 We encourage creating a test build of the docs as well.
108 123
109 124 6. Create and push the new tag
110 125 ------------------------------
111 126
112 127 Commit the changes to release.py::
113 128
114 129 git commit -am "release $VERSION"
115 130 git push origin $BRANCH
116 131
117 132 Create and push the tag::
118 133
119 134 git tag -am "release $VERSION" "$VERSION"
120 135 git push origin --tags
121 136
122 Update release.py back to `x.y-dev` or `x.y-maint`, and re-add the
123 `development` entry in `docs/source/whatsnew/index.rst` and push::
137 Update release.py back to ``x.y-dev`` or ``x.y-maint``, and re-add the
138 ``development`` entry in ``docs/source/whatsnew/index.rst`` and push::
124 139
125 140 git commit -am "back to development"
126 141 git push origin $BRANCH
127 142
128 143 7. Get a fresh clone
129 144 --------------------
130 145
131 146 Get a fresh clone of the tag for building the release::
132 147
133 148 cd /tmp
134 149 git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION"
150 cd ipython
151
152 .. note::
153
154 You can aslo cleanup the current working repository with ``git clean -xfdi``
135 155
136 156 8. Run the release script
137 157 -------------------------
138 158
139 Run the `release` script, this step requires having a current wheel, Python >=3.4 and Python 2.7.::
159 Run the ``release`` script, this step requires having a current wheel, Python
160 >=3.4 and Python 2.7.::
140 161
141 cd tools && ./release
162 ./tools/release
142 163
143 This makes the tarballs, zipfiles, and wheels, and put them under the `dist/`
164 This makes the tarballs, zipfiles, and wheels, and put them under the ``dist/``
144 165 folder. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading
145 166 them to PyPI.
146 167
147 Use the following to actually upload the result of the build:
168 Use the following to actually upload the result of the build::
148 169
149 ./release upload
170 ./tools/release upload
150 171
151 It should posts them to ``archive.ipython.org`` and registers the release
152 with PyPI if you have the various authorisations.
172 It should posts them to ``archive.ipython.org``.
153 173
154 You might need to use `twine <https://github.com/pypa/twine>`_ (`twine upload
155 dist/*`) manually to actually upload on PyPI. Unlike setuptools, twine is able
174 You will need to use `twine <https://github.com/pypa/twine>`_ (``twine upload
175 dist/*``) manually to actually upload on PyPI. Unlike setuptools, twine is able
156 176 to upload packages over SSL.
157 177
158 178
179 PyPI/Warehouse will automatically hide previous releases. If you are uploading
180 a non-stable version, make sure to log-in to PyPI and un-hide previous version.
181
182
159 183 9. Draft a short release announcement
160 184 -------------------------------------
161 185
162 186 The announcement should include:
163 187
164 188 - release highlights
165 189 - a link to the html version of the *What's new* section of the documentation
166 190 - a link to upgrade or installation tips (if necessary)
167 191
168 192 Post the announcement to the mailing list and or blog, and link from Twitter.
169 193
194 .. note::
195
196 If you are doing a RC or Beta, you can likely skip the next steps.
197
170 198 10. Update milestones on GitHub
171 199 -------------------------------
172 200
173 201 These steps will bring milestones up to date:
174 202
175 203 - close the just released milestone
176 204 - open a new milestone for the next release (x, y+1), if the milestone doesn't
177 205 exist already
178 206
179 207 11. Update the IPython website
180 208 ------------------------------
181 209
182 210 The IPython website should document the new release:
183 211
184 212 - add release announcement (news, announcements)
185 213 - update current version and download links
186 214 - update links on the documentation page (especially if a major release)
187 215
188 216 12. Celebrate!
189 217 --------------
190 218
191 219 Celebrate the release and please thank the contributors for their work. Great
192 220 job!
193 221
General Comments 0
You need to be logged in to leave comments. Login now