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