##// END OF EJS Templates
Flatten useless nesting in Coredev docs.
Matthias Bussonnier -
Show More
@@ -1,76 +1,309
1 1 .. _core_developer_guide:
2 2
3 3 =================================
4 4 Guide for IPython core Developers
5 5 =================================
6 6
7 7 This guide documents the development of IPython itself. Alternatively,
8 8 developers of third party tools and libraries that use IPython should see the
9 9 :doc:`../development/index`.
10 10
11 11
12 12 For instructions on how to make a developer install see :ref:`devinstall`.
13 13
14 .. toctree::
15 :maxdepth: 1
16
17 release_process
18
19
20 14 Backporting Pull requests
21 15 -------------------------
22 16
23 17 All pull requests should usually be made against ``master``, if a Pull Request
24 18 need to be backported to an earlier release; then it should be tagged with the
25 19 correct ``milestone``.
26 20
27 21 If you are an admin on the IPython repository just mention the **backport bot** to
28 22 do the work for you. The bot is evolving so instructions may be different. At
29 23 the time of this writing you can use::
30 24
31 25 @meeseeksdev[bot] backport to <branchname>
32 26
33 27 The bot will attempt to backport the current pull-request and issue a PR if
34 28 possible.
35 29
36 30 .. note::
37 31
38 32 The ``@`` and ``[dev]`` when mentioning the bot should be optional and can
39 33 be omitted.
40 34
41 35
42 36 Backport with ghpro
43 37 -------------------
44 38
45 39 We can also use `ghpro <https://pypi.python.org/pypi/ghpro>`
46 40 to automatically list and apply the PR on other branches. For example:
47 41
48 42 .. code-block:: bash
49 43
50 44 $ backport-pr todo --milestone 5.2
51 45 [...snip..]
52 46 The following PRs have been backported
53 47 9848
54 48 9851
55 49 9953
56 50 9955
57 51 The following PRs should be backported:
58 52 9417
59 53 9863
60 54 9925
61 55 9947
62 56
63 57 $ backport-pr apply 5.x 9947
64 58 [...snip...]
65 59
66 60
61 .. _release_process:
62
63 =======================
64 IPython release process
65 =======================
66
67 This document contains the process that is used to create an IPython release.
68
69 Conveniently, the ``release`` script in the ``tools`` directory of the ``IPython``
70 repository automates most of the release process. This document serves as a
71 handy reminder and checklist for the release manager.
72
73 During the release process, you might need the extra following dependencies:
74
75 - ``keyring`` to access your GitHub authentication tokens
76 - ``graphviz`` to generate some graphs in the documentation
77
78 Make sure you have all the required dependencies to run the tests as well.
79
80
81 1. Set Environment variables
82 ----------------------------
83
84 Set environment variables to document previous release tag, current
85 release milestone, current release version, and git tag.
86
87 These variables may be used later to copy/paste as answers to the script
88 questions instead of typing the appropriate command when the time comes. These
89 variables are not used by the scripts directly; therefore, there is no need to
90 ``export`` them. The format for bash is as follows, but note that these values
91 are just an example valid only for the 5.0 release; you'll need to update them
92 for the release you are actually making::
93
94 PREV_RELEASE=4.2.1
95 MILESTONE=5.0
96 VERSION=5.0.0
97 BRANCH=master
98
99
100 2. Create GitHub stats and finish release note
101 ----------------------------------------------
102
103 .. note::
104
105 This step is optional if making a Beta or RC release.
106
107 .. note::
108
109 Before generating the GitHub stats, verify that all closed issues and pull
110 requests have `appropriate milestones
111 <https://github.com/ipython/ipython/wiki/Dev:-GitHub-workflow#milestones>`_.
112 `This search
113 <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
114 should return no results before creating the GitHub stats.
115
116 If a major release:
117
118 - merge any pull request notes into what's new::
119
120 python tools/update_whatsnew.py
121
122 - update ``docs/source/whatsnew/development.rst``, to ensure it covers
123 the major release features
124
125 - move the contents of ``development.rst`` to ``versionX.rst`` where ``X`` is
126 the numerical release version
127
128 - generate summary of GitHub contributions, which can be done with::
129
130 python tools/github_stats.py --milestone $MILESTONE > stats.rst
131
132 which may need some manual cleanup of ``stats.rst``. Add the cleaned
133 ``stats.rst`` results to ``docs/source/whatsnew/github-stats-X.rst``
134 where ``X`` is the numerical release version (don't forget to add it to
135 the git repo as well). If creating a major release, make a new
136 ``github-stats-X.rst`` file; if creating a minor release, the content
137 from ``stats.rst`` may simply be added to the top of an existing
138 ``github-stats-X.rst`` file. Finally, edit
139 ``docs/source/whatsnew/index.rst`` to list the new ``github-stats-X``
140 file you just created and remove temporarily the first entry called
141 ``development`` (you'll need to add it back after release).
142
143 Make sure that the stats file has a header or it won't be rendered in
144 the final documentation.
145
146 To find duplicates and update `.mailmap`, use::
147
148 git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
149
150 If a minor release you might need to do some of the above points manually, and
151 forward port the changes.
152
153 3. Make sure the repository is clean
154 ------------------------------------
155
156 of any file that could be problematic.
157 Remove all non-tracked files with:
158
159 .. code::
160
161 git clean -xfdi
162
163 This will ask for confirmation before removing all untracked files. Make
164 sure the ``dist/`` folder is clean to avoid any stale builds from
165 previous build attempts.
166
167
168 4. Update the release version number
169 ------------------------------------
170
171 Edit ``IPython/core/release.py`` to have the current version.
172
173 in particular, update version number and ``_version_extra`` content in
174 ``IPython/core/release.py``.
175
176 Step 5 will validate your changes automatically, but you might still want to
177 make sure the version number matches pep440.
178
179 In particular, ``rc`` and ``beta`` are not separated by ``.`` or the ``sdist``
180 and ``bdist`` will appear as different releases. For example, a valid version
181 number for a release candidate (rc) release is: ``1.3rc1``. Notice that there
182 is no separator between the '3' and the 'r'. Check the environment variable
183 ``$VERSION`` as well.
184
185 You will likely just have to modify/comment/uncomment one of the lines setting
186 ``_version_extra``
187
188
189 5. Run the `tools/build_release` script
190 ---------------------------------------
191
192 Running ``tools/build_release`` does all the file checking and building that
193 the real release script will do. This makes test installations, checks that
194 the build procedure runs OK, and tests other steps in the release process.
195
196 The ``build_release`` script will in particular verify that the version number
197 match PEP 440, in order to avoid surprise at the time of build upload.
198
199 We encourage creating a test build of the docs as well.
200
201 6. Create and push the new tag
202 ------------------------------
203
204 Commit the changes to release.py::
205
206 git commit -am "release $VERSION"
207 git push origin $BRANCH
208
209 Create and push the tag::
210
211 git tag -am "release $VERSION" "$VERSION"
212 git push origin --tags
213
214 Update release.py back to ``x.y-dev`` or ``x.y-maint``, and re-add the
215 ``development`` entry in ``docs/source/whatsnew/index.rst`` and push::
216
217 git commit -am "back to development"
218 git push origin $BRANCH
219
220 Now checkout the tag we just made::
221
222 git checkout $VERSION
223
224 7. Run the release script
225 -------------------------
226
227 Run the ``release`` script, this step requires having a current wheel, Python
228 >=3.4 and Python 2.7.::
229
230 ./tools/release
231
232 This makes the tarballs and wheels, and puts them under the ``dist/``
233 folder. Be sure to test the ``wheels`` and the ``sdist`` locally before
234 uploading them to PyPI. We do not use an universal wheel as each wheel
235 installs an ``ipython2`` or ``ipython3`` script, depending on the version of
236 Python it is built for. Using an universal wheel would prevent this.
237
238 Use the following to actually upload the result of the build::
239
240 ./tools/release upload
241
242 It should posts them to ``archive.ipython.org`` and to PyPI.
243
244 PyPI/Warehouse will automatically hide previous releases. If you are uploading
245 a non-stable version, make sure to log-in to PyPI and un-hide previous version.
246
247
248 8. Draft a short release announcement
249 -------------------------------------
250
251 The announcement should include:
252
253 - release highlights
254 - a link to the html version of the *What's new* section of the documentation
255 - a link to upgrade or installation tips (if necessary)
256
257 Post the announcement to the mailing list and or blog, and link from Twitter.
258
259 .. note::
260
261 If you are doing a RC or Beta, you can likely skip the next steps.
262
263 9. Update milestones on GitHub
264 -------------------------------
265
266 These steps will bring milestones up to date:
267
268 - close the just released milestone
269 - open a new milestone for the next release (x, y+1), if the milestone doesn't
270 exist already
271
272 10. Update the IPython website
273 ------------------------------
274
275 The IPython website should document the new release:
276
277 - add release announcement (news, announcements)
278 - update current version and download links
279 - update links on the documentation page (especially if a major release)
280
281 11. Update readthedocs
282 ----------------------
283
284 Make sure to update readthedocs and set the latest tag as stable, as well as
285 checking that previous release is still building under its own tag.
286
287 12. Update the Conda-Forge feedstock
288 ------------------------------------
289
290 Follow the instructions on `the repository <https://github.com/conda-forge/ipython-feedstock>`_
291
292 13. Celebrate!
293 --------------
294
295 Celebrate the release and please thank the contributors for their work. Great
296 job!
297
298
299
67 300 Old Documentation
68 301 =================
69 302
70 303 Out of date documentation is still available and have been kept for archival purposes.
71 304
72 305 .. note::
73 306
74 307 Developers documentation used to be on the IPython wiki, but are now out of
75 308 date. The wiki is though still available for historical reasons: `Old IPython
76 309 GitHub Wiki. <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
1 NO CONTENT: file was removed
General Comments 0
You need to be logged in to leave comments. Login now