##// END OF EJS Templates
Update release instructions for stats inclusion in whatsnew section.
Fernando Perez -
Show More
@@ -1,221 +1,224 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 17 release milestone, current release version, and git tag.
18 18
19 19 These variables may be used later to copy/paste as answers to the script
20 20 questions instead of typing the appropriate command when the time comes. These
21 21 variables are not used by the scripts directly; therefore, there is no need to
22 ``export`` the variables. Use the following in bash::
22 ``export`` them. The format for bash is as follows, but note that these values
23 are just an example valid only for the 5.0 release; you'll need to update them
24 for the release you are actually making::
23 25
24 26 PREV_RELEASE=4.2.1
25 27 MILESTONE=5.0
26 28 VERSION=5.0.0
27 29 BRANCH=master
28 30
29 31
30 32 2. Create GitHub stats and finish release note
31 33 ----------------------------------------------
32 34
33 35 .. note::
34 36
35 37 This step is optional if making a Beta or RC release.
36 38
37 39 .. note::
38 40
39 41 Before generating the GitHub stats, verify that all closed issues and pull
40 42 requests have `appropriate milestones
41 43 <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
42 44 `This search
43 45 <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
44 46 should return no results before creating the GitHub stats.
45 47
46 48 If a major release:
47 49
48 50 - merge any pull request notes into what's new::
49 51
50 52 python tools/update_whatsnew.py
51 53
52 54 - update ``docs/source/whatsnew/development.rst``, to ensure it covers
53 55 the major release features
54 56
55 57 - move the contents of ``development.rst`` to ``versionX.rst`` where ``X`` is
56 58 the numerical release version
57 59
58 60 - generate summary of GitHub contributions, which can be done with::
59 61
60 62 python tools/github_stats.py --milestone $MILESTONE > stats.rst
61 63
62 64 which may need some manual cleanup of ``stats.rst``. Add the cleaned
63 65 ``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.
66 where ``X`` is the numerical release version (don't forget to add it to
67 the git repo as well). If creating a major release, make a new
68 ``github-stats-X.rst`` file; if creating a minor release, the content
69 from ``stats.rst`` may simply be added to the top of an existing
70 ``github-stats-X.rst`` file. Finally, edit
71 ``docs/source/whatsnew/index.rst`` to list the new ``github-stats-X``
72 file you just created and remove temporarily the first entry called
73 ``development`` (you'll need to add it back after release).
68 74
69 75 To find duplicates and update `.mailmap`, use::
70 76
71 77 git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
72 78
73 79 3. Make sure the repository is clean
74 80 ------------------------------------
75 81
76 82 of any file that could be problematic.
77 83 Remove all non-tracked files with:
78 84
79 85 .. code::
80 86
81 87 git clean -xfdi
82 88
83 89 This will ask for confirmation before removing all untracked files. Make
84 90 sure the ``dist/`` folder is clean to avoid any stale builds from
85 91 previous build attempts.
86 92
87 93
88 94 4. Update the release version number
89 95 ------------------------------------
90 96
91 97 Edit ``IPython/core/release.py`` to have the current version.
92 98
93 99 in particular, update version number and ``_version_extra`` content in
94 100 ``IPython/core/release.py``.
95 101
96 102 Step 5 will validate your changes automatically, but you might still want to
97 103 make sure the version number matches pep440.
98 104
99 105 In particular, ``rc`` and ``beta`` are not separated by ``.`` or the ``sdist``
100 106 and ``bdist`` will appear as different releases. For example, a valid version
101 107 number for a release candidate (rc) release is: ``1.3rc1``. Notice that there
102 108 is no separator between the '3' and the 'r'. Check the environment variable
103 109 ``$VERSION`` as well.
104 110
105 111 You will likely just have to modify/comment/uncomment one of the lines setting
106 112 ``_version_extra``
107 113
108 114
109 Comment remove the ``development`` entry in ``whatsnew/index.rst``. TODO, figure
110 out how to make that automatic.
111
112 115 5. Run the `tools/build_release` script
113 116 ---------------------------------------
114 117
115 118 Running ``tools/build_release`` does all the file checking and building that
116 119 the real release script will do. This makes test installations, checks that
117 120 the build procedure runs OK, and tests other steps in the release process.
118 121
119 122 The ``build_release`` script will in particular verify that the version number
120 123 match PEP 440, in order to avoid surprise at the time of build upload.
121 124
122 125 We encourage creating a test build of the docs as well.
123 126
124 127 6. Create and push the new tag
125 128 ------------------------------
126 129
127 130 Commit the changes to release.py::
128 131
129 132 git commit -am "release $VERSION"
130 133 git push origin $BRANCH
131 134
132 135 Create and push the tag::
133 136
134 137 git tag -am "release $VERSION" "$VERSION"
135 138 git push origin --tags
136 139
137 140 Update release.py back to ``x.y-dev`` or ``x.y-maint``, and re-add the
138 141 ``development`` entry in ``docs/source/whatsnew/index.rst`` and push::
139 142
140 143 git commit -am "back to development"
141 144 git push origin $BRANCH
142 145
143 146 7. Get a fresh clone
144 147 --------------------
145 148
146 149 Get a fresh clone of the tag for building the release::
147 150
148 151 cd /tmp
149 152 git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION"
150 153 cd ipython
151 154
152 155 .. note::
153 156
154 157 You can aslo cleanup the current working repository with ``git clean -xfdi``
155 158
156 159 8. Run the release script
157 160 -------------------------
158 161
159 162 Run the ``release`` script, this step requires having a current wheel, Python
160 163 >=3.4 and Python 2.7.::
161 164
162 165 ./tools/release
163 166
164 167 This makes the tarballs, zipfiles, and wheels, and put them under the ``dist/``
165 168 folder. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading
166 169 them to PyPI.
167 170
168 171 Use the following to actually upload the result of the build::
169 172
170 173 ./tools/release upload
171 174
172 175 It should posts them to ``archive.ipython.org``.
173 176
174 177 You will need to use `twine <https://github.com/pypa/twine>`_ (``twine upload
175 178 dist/*``) manually to actually upload on PyPI. Unlike setuptools, twine is able
176 179 to upload packages over SSL.
177 180
178 181
179 182 PyPI/Warehouse will automatically hide previous releases. If you are uploading
180 183 a non-stable version, make sure to log-in to PyPI and un-hide previous version.
181 184
182 185
183 186 9. Draft a short release announcement
184 187 -------------------------------------
185 188
186 189 The announcement should include:
187 190
188 191 - release highlights
189 192 - a link to the html version of the *What's new* section of the documentation
190 193 - a link to upgrade or installation tips (if necessary)
191 194
192 195 Post the announcement to the mailing list and or blog, and link from Twitter.
193 196
194 197 .. note::
195 198
196 199 If you are doing a RC or Beta, you can likely skip the next steps.
197 200
198 201 10. Update milestones on GitHub
199 202 -------------------------------
200 203
201 204 These steps will bring milestones up to date:
202 205
203 206 - close the just released milestone
204 207 - open a new milestone for the next release (x, y+1), if the milestone doesn't
205 208 exist already
206 209
207 210 11. Update the IPython website
208 211 ------------------------------
209 212
210 213 The IPython website should document the new release:
211 214
212 215 - add release announcement (news, announcements)
213 216 - update current version and download links
214 217 - update links on the documentation page (especially if a major release)
215 218
216 219 12. Celebrate!
217 220 --------------
218 221
219 222 Celebrate the release and please thank the contributors for their work. Great
220 223 job!
221 224
@@ -1,44 +1,44 b''
1 1 .. Developers should add in this file, during each release cycle, information
2 2 .. about important changes they've made, in a summary format that's meant for
3 3 .. end users. For each release we normally have three sections: features, bug
4 4 .. fixes and api breakage.
5 5 .. Please remember to credit the authors of the contributions by name,
6 6 .. especially when they are new users or developers who do not regularly
7 7 .. participate in IPython's development.
8 8
9 9 .. _whatsnew_index:
10 10
11 11 =====================
12 12 What's new in IPython
13 13 =====================
14 14
15 15 This section documents the changes that have been made in various versions of
16 16 IPython. Users should consult these pages to learn about new features, bug
17 17 fixes and backwards incompatibilities. Developers should summarize the
18 18 development work they do here in a user friendly format.
19 19
20 20 .. toctree::
21 21 :maxdepth: 1
22 22
23 development
24 23 version5
24 github-stats-5
25 25 version4
26 26 github-stats-4
27 27 version3
28 28 github-stats-3
29 29 version3_widget_migration
30 30 version2.0
31 31 github-stats-2.0
32 32 version1.0
33 33 github-stats-1.0
34 34 version0.13
35 35 github-stats-0.13
36 36 version0.12
37 37 github-stats-0.12
38 38 version0.11
39 39 github-stats-0.11
40 40 version0.10
41 41 version0.9
42 42 version0.8
43 43
44 44
General Comments 0
You need to be logged in to leave comments. Login now