From 453d1058a2e1698f636f38c8443090f5670f1c38 2016-01-29 07:34:40 From: Min RK Date: 2016-01-29 07:34:40 Subject: [PATCH] Merge pull request #9193 from willingc/doc-release Migrate release creation instructions from wiki to docs --- diff --git a/docs/source/coredev/index.rst b/docs/source/coredev/index.rst new file mode 100644 index 0000000..0999547 --- /dev/null +++ b/docs/source/coredev/index.rst @@ -0,0 +1,19 @@ +.. _core_developer_guide: + +================================== +Developer's guide to core IPython +================================== + +This guide documents the development of core IPython. Alternatively, +developers of third party tools and libraries that use IPython should see the +:doc:`../development/index`. + +Developers working on core IPython should also consult the +`developer information `_ +on the IPython GitHub wiki. + +.. toctree:: + :maxdepth: 1 + + release_process + making_release diff --git a/docs/source/coredev/making_release.rst b/docs/source/coredev/making_release.rst new file mode 100644 index 0000000..273d5af --- /dev/null +++ b/docs/source/coredev/making_release.rst @@ -0,0 +1,56 @@ +.. making_release:: + +Making an IPython release +========================= + +1. Make sure the repository is clean of any file that could be problematic. + Remove all non-tracked files with: + + .. code:: + + git clean -xfdi + + This will ask for confirmation before removing all untracked files. Make + sure the ``dist/`` folder is clean to avoid any stale builds from + previous build attempts. + +2. Update version number and ``_version_extra`` content in + ``IPython/core/release.py``. + + Make sure the version number matches pep440, in particular, `rc` and `beta` + are not separated by `.` or the `sdist` and `bdist` will appear as different + releases. For example, a valid version number for a release candidate (rc) + release is: ``1.3rc1``. Notice that there is no separator between the '3' + and the 'r'. + + +3. Commit and tag the release with the current version number: + + .. code:: + + git commit -am "release $VERSION" + git tag $VERSION + + +4. Build the ``sdist`` and ``wheel``: + + .. code:: + + python setup.py sdist --formats=zip,gztar + python2 setup.py bdist_wheel + python3 setup.py bdist_wheel + + +5. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading + them to PyPI. Make sure to use `twine `_ to + upload these archives over SSL. + + .. code:: + + $ twine upload dist/* + +6. If all went well, change the ``_version_extra = ''`` in + ``IPython/core/release.py`` back to the ``.dev`` suffix, or + ``_version_extra='.dev'``. + +7. Push directly to master, remembering to push ``--tags`` too. \ No newline at end of file diff --git a/docs/source/coredev/release_process.rst b/docs/source/coredev/release_process.rst new file mode 100644 index 0000000..87715fa --- /dev/null +++ b/docs/source/coredev/release_process.rst @@ -0,0 +1,149 @@ +.. _release_process: + +======================= +IPython release process +======================= + +This document contains the process that is used to create an IPython release. + +Conveniently, the `release` script in the `tools` directory of the `IPython` +repository automates most of the release process. This document serves as a +handy reminder and checklist for the release manager. + +1. Set Environment variables +---------------------------- + +Set environment variables to document previous release tag, current +release milestone, current release version, and git tag:: + + PREV_RELEASE=rel-1.0.0 + MILESTONE=1.1 + VERSION=1.1.0 + TAG="rel-$VERSION" + BRANCH=master + +These variables may be used later to copy/paste as answers to the script +questions instead of typing the appropriate command when the time comes. These +variables are not used by the scripts directly; therefore, there is no need to +`export` the variables. + +2. Create GitHub stats and finish release note +---------------------------------------------- + +.. note:: + + Before generating the GitHub stats, verify that all closed issues and + pull requests have `appropriate milestones `_. + `This search `_ + should return no results before creating the GitHub stats. + +If a major release: + + - merge any pull request notes into what's new:: + + python tools/update_whatsnew.py + + - update `docs/source/whatsnew/development.rst`, to ensure it covers + the major release features + - move the contents of `development.rst` to `versionX.rst` where `X` is + the numerical release version + - generate summary of GitHub contributions, which can be done with:: + + python tools/github_stats.py --milestone $MILESTONE > stats.rst + + which may need some manual cleanup of `stats.rst`. Add the cleaned + `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where + `X` is the numerical release version. If creating a major release, make + a new `github-stats-X.rst` file; if creating a minor release, the + content from `stats.rst` may simply be added to the top of an existing + `github-stats-X.rst` file. + +To find duplicates and update `.mailmap`, use:: + + git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f + + +3. Run the `tools/build_release` script +--------------------------------------- + +Running `tools/build_release` does all the file checking and building that +the real release script will do. This makes test installations, checks that +the build procedure runs OK, and tests other steps in the release process. + +We encourage creating a test build of the docs as well. + +4. Create and push the new tag +------------------------------ + +Edit `IPython/core/release.py` to have the current version. + +Commit the changes to release.py and jsversion:: + + git commit -am "release $VERSION" + git push origin $BRANCH + +Create and push the tag:: + + git tag -am "release $VERSION" "$TAG" + git push origin --tags + +Update release.py back to `x.y-dev` or `x.y-maint`, and push:: + + git commit -am "back to development" + git push origin $BRANCH + +5. Get a fresh clone +-------------------- + +Get a fresh clone of the tag for building the release:: + + cd /tmp + git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG" + +6. Run the release script +------------------------- + +Run the `release` script:: + + cd tools && ./release + +This makes the tarballs, zipfiles, and wheels. It posts +them to archive.ipython.org and registers the release with PyPI. + +This step requires having a current wheel, Python 3.4 and Python 2.7. + +7. Draft a short release announcement +------------------------------------- + +The announcement should include: + +- release highlights +- a link to the html version of the *What's new* section of the documentation +- a link to upgrade or installation tips (if necessary) + +Post the announcement to the mailing list, and link from Twitter. + +8. Update milestones on GitHub +------------------------------ + +These steps will bring milestones up to date: + +- close the just released milestone +- open a new milestone for the next release (x, y+1), if the milestone doesn't + exist already + +9. Update the IPython website +----------------------------- + +The IPython website should document the new release: + +- add release announcement (news, announcements) +- update current version and download links +- update links on the documentation page (especially if a major release) + +10. Celebrate! +-------------- + +Celebrate the release and please thank the contributors for their work. Great +job! + diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 2553d22..a945625 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -1,20 +1,14 @@ .. _developer_guide: -========================= -IPython developer's guide -========================= +===================================================== +Developer's guide for third party tools and libraries +===================================================== -This are two categories of developer focused documentation: +.. important:: -1. Documentation for developers of *IPython itself*. -2. Documentation for developers of third party tools and libraries - that use IPython. - -This part of our documentation only contains information in the second category. - -Developers interested in working on IPython itself should consult -our `developer information `_ -on the IPython GitHub wiki. + This guide contains information for developers of third party tools and + libraries that use IPython. Alternatively, documentation for core + **IPython** development can be found in the :doc:`../coredev/index`. .. toctree:: :maxdepth: 1 @@ -25,53 +19,4 @@ on the IPython GitHub wiki. lexer pycompat config - inputhook_app - -Making an IPython release -========================= - -Make sure the repository is clean of any file that could be problematic. -You can remove all non-tracked files with: - -.. code:: - - git clean -xfdi - -This would ask you for confirmation before removing all untracked files. Make -sure the ``dist/`` folder is clean and avoid stale build from -previous attempts. - -1. Update version number in ``IPython/core/release.py``. - -Make sure the version number match pep440, in particular, `rc` and `beta` are -not separated by `.` or the `sdist` and `bdist` will appear as different -releases. - -2. Commit and tag the release with the current version number: - -.. code:: - - git commit -am "release $VERSION" - git tag $VERSION - - -3. You are now ready to build the ``sdist`` and ``wheel``: - -.. code:: - - python setup.py sdist --formats=zip,gztar - python2 setup.py bdist_wheel - python3 setup.py bdist_wheel - - -4. You can now test the ``wheel`` and the ``sdist`` locally before uploading to PyPI. -Make sure to use `twine `_ to upload the archives over SSL. - -.. code:: - - $ twine upload dist/* - -5. If all went well, change the ``IPython/core/release.py`` back adding the ``.dev`` suffix. - -6. Push directly on master, not forgetting to push ``--tags``. - + inputhook_app \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 4423601..fc948f1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,6 +21,7 @@ Contents interactive/index config/index development/index + coredev/index api/index about/index