##// END OF EJS Templates
Merge pull request #9193 from willingc/doc-release...
Min RK -
r22033:453d1058 merge
parent child Browse files
Show More
@@ -0,0 +1,19 b''
1 .. _core_developer_guide:
2
3 ==================================
4 Developer's guide to core IPython
5 ==================================
6
7 This guide documents the development of core IPython. Alternatively,
8 developers of third party tools and libraries that use IPython should see the
9 :doc:`../development/index`.
10
11 Developers working on core IPython should also consult the
12 `developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
13 on the IPython GitHub wiki.
14
15 .. toctree::
16 :maxdepth: 1
17
18 release_process
19 making_release
@@ -0,0 +1,56 b''
1 .. making_release::
2
3 Making an IPython release
4 =========================
5
6 1. Make sure the repository is clean of any file that could be problematic.
7 Remove all non-tracked files with:
8
9 .. code::
10
11 git clean -xfdi
12
13 This will ask for confirmation before removing all untracked files. Make
14 sure the ``dist/`` folder is clean to avoid any stale builds from
15 previous build attempts.
16
17 2. Update version number and ``_version_extra`` content in
18 ``IPython/core/release.py``.
19
20 Make sure the version number matches pep440, in particular, `rc` and `beta`
21 are not separated by `.` or the `sdist` and `bdist` will appear as different
22 releases. For example, a valid version number for a release candidate (rc)
23 release is: ``1.3rc1``. Notice that there is no separator between the '3'
24 and the 'r'.
25
26
27 3. Commit and tag the release with the current version number:
28
29 .. code::
30
31 git commit -am "release $VERSION"
32 git tag $VERSION
33
34
35 4. Build the ``sdist`` and ``wheel``:
36
37 .. code::
38
39 python setup.py sdist --formats=zip,gztar
40 python2 setup.py bdist_wheel
41 python3 setup.py bdist_wheel
42
43
44 5. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading
45 them to PyPI. Make sure to use `twine <https://github.com/pypa/twine>`_ to
46 upload these archives over SSL.
47
48 .. code::
49
50 $ twine upload dist/*
51
52 6. If all went well, change the ``_version_extra = ''`` in
53 ``IPython/core/release.py`` back to the ``.dev`` suffix, or
54 ``_version_extra='.dev'``.
55
56 7. Push directly to master, remembering to push ``--tags`` too. No newline at end of file
@@ -0,0 +1,149 b''
1 .. _release_process:
2
3 =======================
4 IPython release process
5 =======================
6
7 This document contains the process that is used to create an IPython release.
8
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
11 handy reminder and checklist for the release manager.
12
13 1. Set Environment variables
14 ----------------------------
15
16 Set environment variables to document previous release tag, current
17 release milestone, current release version, and git tag::
18
19 PREV_RELEASE=rel-1.0.0
20 MILESTONE=1.1
21 VERSION=1.1.0
22 TAG="rel-$VERSION"
23 BRANCH=master
24
25 These variables may be used later to copy/paste as answers to the script
26 questions instead of typing the appropriate command when the time comes. These
27 variables are not used by the scripts directly; therefore, there is no need to
28 `export` the variables.
29
30 2. Create GitHub stats and finish release note
31 ----------------------------------------------
32
33 .. note::
34
35 Before generating the GitHub stats, verify that all closed issues and
36 pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
37 `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
38 should return no results before creating the GitHub stats.
39
40 If a major release:
41
42 - merge any pull request notes into what's new::
43
44 python tools/update_whatsnew.py
45
46 - update `docs/source/whatsnew/development.rst`, to ensure it covers
47 the major release features
48 - move the contents of `development.rst` to `versionX.rst` where `X` is
49 the numerical release version
50 - generate summary of GitHub contributions, which can be done with::
51
52 python tools/github_stats.py --milestone $MILESTONE > stats.rst
53
54 which may need some manual cleanup of `stats.rst`. Add the cleaned
55 `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where
56 `X` is the numerical release version. If creating a major release, make
57 a new `github-stats-X.rst` file; if creating a minor release, the
58 content from `stats.rst` may simply be added to the top of an existing
59 `github-stats-X.rst` file.
60
61 To find duplicates and update `.mailmap`, use::
62
63 git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
64
65
66 3. Run the `tools/build_release` script
67 ---------------------------------------
68
69 Running `tools/build_release` does all the file checking and building that
70 the real release script will do. This makes test installations, checks that
71 the build procedure runs OK, and tests other steps in the release process.
72
73 We encourage creating a test build of the docs as well.
74
75 4. Create and push the new tag
76 ------------------------------
77
78 Edit `IPython/core/release.py` to have the current version.
79
80 Commit the changes to release.py and jsversion::
81
82 git commit -am "release $VERSION"
83 git push origin $BRANCH
84
85 Create and push the tag::
86
87 git tag -am "release $VERSION" "$TAG"
88 git push origin --tags
89
90 Update release.py back to `x.y-dev` or `x.y-maint`, and push::
91
92 git commit -am "back to development"
93 git push origin $BRANCH
94
95 5. Get a fresh clone
96 --------------------
97
98 Get a fresh clone of the tag for building the release::
99
100 cd /tmp
101 git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG"
102
103 6. Run the release script
104 -------------------------
105
106 Run the `release` script::
107
108 cd tools && ./release
109
110 This makes the tarballs, zipfiles, and wheels. It posts
111 them to archive.ipython.org and registers the release with PyPI.
112
113 This step requires having a current wheel, Python 3.4 and Python 2.7.
114
115 7. Draft a short release announcement
116 -------------------------------------
117
118 The announcement should include:
119
120 - release highlights
121 - a link to the html version of the *What's new* section of the documentation
122 - a link to upgrade or installation tips (if necessary)
123
124 Post the announcement to the mailing list, and link from Twitter.
125
126 8. Update milestones on GitHub
127 ------------------------------
128
129 These steps will bring milestones up to date:
130
131 - close the just released milestone
132 - open a new milestone for the next release (x, y+1), if the milestone doesn't
133 exist already
134
135 9. Update the IPython website
136 -----------------------------
137
138 The IPython website should document the new release:
139
140 - add release announcement (news, announcements)
141 - update current version and download links
142 - update links on the documentation page (especially if a major release)
143
144 10. Celebrate!
145 --------------
146
147 Celebrate the release and please thank the contributors for their work. Great
148 job!
149
@@ -1,20 +1,14 b''
1 .. _developer_guide:
1 .. _developer_guide:
2
2
3 =========================
3 =====================================================
4 IPython developer's guide
4 Developer's guide for third party tools and libraries
5 =========================
5 =====================================================
6
6
7 This are two categories of developer focused documentation:
7 .. important::
8
8
9 1. Documentation for developers of *IPython itself*.
9 This guide contains information for developers of third party tools and
10 2. Documentation for developers of third party tools and libraries
10 libraries that use IPython. Alternatively, documentation for core
11 that use IPython.
11 **IPython** development can be found in the :doc:`../coredev/index`.
12
13 This part of our documentation only contains information in the second category.
14
15 Developers interested in working on IPython itself should consult
16 our `developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
17 on the IPython GitHub wiki.
18
12
19 .. toctree::
13 .. toctree::
20 :maxdepth: 1
14 :maxdepth: 1
@@ -25,53 +19,4 b' on the IPython GitHub wiki.'
25 lexer
19 lexer
26 pycompat
20 pycompat
27 config
21 config
28 inputhook_app
22 inputhook_app No newline at end of file
29
30 Making an IPython release
31 =========================
32
33 Make sure the repository is clean of any file that could be problematic.
34 You can remove all non-tracked files with:
35
36 .. code::
37
38 git clean -xfdi
39
40 This would ask you for confirmation before removing all untracked files. Make
41 sure the ``dist/`` folder is clean and avoid stale build from
42 previous attempts.
43
44 1. Update version number in ``IPython/core/release.py``.
45
46 Make sure the version number match pep440, in particular, `rc` and `beta` are
47 not separated by `.` or the `sdist` and `bdist` will appear as different
48 releases.
49
50 2. Commit and tag the release with the current version number:
51
52 .. code::
53
54 git commit -am "release $VERSION"
55 git tag $VERSION
56
57
58 3. You are now ready to build the ``sdist`` and ``wheel``:
59
60 .. code::
61
62 python setup.py sdist --formats=zip,gztar
63 python2 setup.py bdist_wheel
64 python3 setup.py bdist_wheel
65
66
67 4. You can now test the ``wheel`` and the ``sdist`` locally before uploading to PyPI.
68 Make sure to use `twine <https://github.com/pypa/twine>`_ to upload the archives over SSL.
69
70 .. code::
71
72 $ twine upload dist/*
73
74 5. If all went well, change the ``IPython/core/release.py`` back adding the ``.dev`` suffix.
75
76 6. Push directly on master, not forgetting to push ``--tags``.
77
@@ -21,6 +21,7 b' Contents'
21 interactive/index
21 interactive/index
22 config/index
22 config/index
23 development/index
23 development/index
24 coredev/index
24 api/index
25 api/index
25 about/index
26 about/index
26
27
General Comments 0
You need to be logged in to leave comments. Login now