Show More
@@ -1,76 +1,309 | |||||
1 | .. _core_developer_guide: |
|
1 | .. _core_developer_guide: | |
2 |
|
2 | |||
3 | ================================= |
|
3 | ================================= | |
4 | Guide for IPython core Developers |
|
4 | Guide for IPython core Developers | |
5 | ================================= |
|
5 | ================================= | |
6 |
|
6 | |||
7 | This guide documents the development of IPython itself. Alternatively, |
|
7 | This guide documents the development of IPython itself. Alternatively, | |
8 | developers of third party tools and libraries that use IPython should see the |
|
8 | developers of third party tools and libraries that use IPython should see the | |
9 | :doc:`../development/index`. |
|
9 | :doc:`../development/index`. | |
10 |
|
10 | |||
11 |
|
11 | |||
12 | For instructions on how to make a developer install see :ref:`devinstall`. |
|
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 | Backporting Pull requests |
|
14 | Backporting Pull requests | |
21 | ------------------------- |
|
15 | ------------------------- | |
22 |
|
16 | |||
23 | All pull requests should usually be made against ``master``, if a Pull Request |
|
17 | All pull requests should usually be made against ``master``, if a Pull Request | |
24 | need to be backported to an earlier release; then it should be tagged with the |
|
18 | need to be backported to an earlier release; then it should be tagged with the | |
25 | correct ``milestone``. |
|
19 | correct ``milestone``. | |
26 |
|
20 | |||
27 | If you are an admin on the IPython repository just mention the **backport bot** to |
|
21 | If you are an admin on the IPython repository just mention the **backport bot** to | |
28 | do the work for you. The bot is evolving so instructions may be different. At |
|
22 | do the work for you. The bot is evolving so instructions may be different. At | |
29 | the time of this writing you can use:: |
|
23 | the time of this writing you can use:: | |
30 |
|
24 | |||
31 | @meeseeksdev[bot] backport to <branchname> |
|
25 | @meeseeksdev[bot] backport to <branchname> | |
32 |
|
26 | |||
33 | The bot will attempt to backport the current pull-request and issue a PR if |
|
27 | The bot will attempt to backport the current pull-request and issue a PR if | |
34 | possible. |
|
28 | possible. | |
35 |
|
29 | |||
36 | .. note:: |
|
30 | .. note:: | |
37 |
|
31 | |||
38 | The ``@`` and ``[dev]`` when mentioning the bot should be optional and can |
|
32 | The ``@`` and ``[dev]`` when mentioning the bot should be optional and can | |
39 | be omitted. |
|
33 | be omitted. | |
40 |
|
34 | |||
41 |
|
35 | |||
42 | Backport with ghpro |
|
36 | Backport with ghpro | |
43 | ------------------- |
|
37 | ------------------- | |
44 |
|
38 | |||
45 | We can also use `ghpro <https://pypi.python.org/pypi/ghpro>` |
|
39 | We can also use `ghpro <https://pypi.python.org/pypi/ghpro>` | |
46 | to automatically list and apply the PR on other branches. For example: |
|
40 | to automatically list and apply the PR on other branches. For example: | |
47 |
|
41 | |||
48 | .. code-block:: bash |
|
42 | .. code-block:: bash | |
49 |
|
43 | |||
50 | $ backport-pr todo --milestone 5.2 |
|
44 | $ backport-pr todo --milestone 5.2 | |
51 | [...snip..] |
|
45 | [...snip..] | |
52 | The following PRs have been backported |
|
46 | The following PRs have been backported | |
53 | 9848 |
|
47 | 9848 | |
54 | 9851 |
|
48 | 9851 | |
55 | 9953 |
|
49 | 9953 | |
56 | 9955 |
|
50 | 9955 | |
57 | The following PRs should be backported: |
|
51 | The following PRs should be backported: | |
58 | 9417 |
|
52 | 9417 | |
59 | 9863 |
|
53 | 9863 | |
60 | 9925 |
|
54 | 9925 | |
61 | 9947 |
|
55 | 9947 | |
62 |
|
56 | |||
63 | $ backport-pr apply 5.x 9947 |
|
57 | $ backport-pr apply 5.x 9947 | |
64 | [...snip...] |
|
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 | Old Documentation |
|
300 | Old Documentation | |
68 | ================= |
|
301 | ================= | |
69 |
|
302 | |||
70 | Out of date documentation is still available and have been kept for archival purposes. |
|
303 | Out of date documentation is still available and have been kept for archival purposes. | |
71 |
|
304 | |||
72 | .. note:: |
|
305 | .. note:: | |
73 |
|
306 | |||
74 | Developers documentation used to be on the IPython wiki, but are now out of |
|
307 | Developers documentation used to be on the IPython wiki, but are now out of | |
75 | date. The wiki is though still available for historical reasons: `Old IPython |
|
308 | date. The wiki is though still available for historical reasons: `Old IPython | |
76 | GitHub Wiki. <https://github.com/ipython/ipython/wiki/Dev:-Index>`_ |
|
309 | GitHub Wiki. <https://github.com/ipython/ipython/wiki/Dev:-Index>`_ |
1 | NO CONTENT: file was removed |
|
NO CONTENT: file was removed |
General Comments 0
You need to be logged in to leave comments.
Login now