From 8532e5ef0777d78870d88d5cfafd657b189a82d9 2016-01-28 22:28:33 From: Carol Willing Date: 2016-01-28 22:28:33 Subject: [PATCH] Migrate the wiki contents to release process doc --- diff --git a/docs/source/coredev/index.rst b/docs/source/coredev/index.rst index 3d5445c..306b8cc 100644 --- a/docs/source/coredev/index.rst +++ b/docs/source/coredev/index.rst @@ -16,52 +16,4 @@ on the IPython GitHub wiki. :maxdepth: 1 release_process - -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``. - + old_release_doc diff --git a/docs/source/coredev/old_release_doc.rst b/docs/source/coredev/old_release_doc.rst new file mode 100644 index 0000000..480cc96 --- /dev/null +++ b/docs/source/coredev/old_release_doc.rst @@ -0,0 +1,50 @@ +.. old_release_doc:: + +Making an IPython release [TODO:: Can this be replaced by the Release Process document???] +========================================================================================== + +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``. + diff --git a/docs/source/coredev/release_process.rst b/docs/source/coredev/release_process.rst index f45b7a7..c6e312f 100644 --- a/docs/source/coredev/release_process.rst +++ b/docs/source/coredev/release_process.rst @@ -1,13 +1,20 @@ -This document contains notes about the process that is used to release IPython. -Our release process is currently not very formal and could be improved. +.. _release_process: -Most of the release process is automated by the `release` script in the `tools` -directory of our main repository. This document is just a handy reminder for -the release manager. +====================== +Releasing core IPython +====================== -# 0. Environment variables +This document contains the process that is used to create an IPython release. -You can set some env variables to note previous release tag and current release milestone, version, and git tag: +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. + +#. 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 @@ -15,37 +22,58 @@ You can set some env variables to note previous release tag and current release TAG="rel-$VERSION" BRANCH=master -These will be used later if you want to copy/paste, or you can just type the appropriate command when the time comes. These variables are not used by scripts (hence no `export`). +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. + +#. Finish release notes +----------------------- + +.. note:: -# 1. Finish release notes + 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: +If a major release: - - merge any pull request notes into what's new: + - 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 points. - - move the contents of `development.rst` to `versionX.rst` -- generate summary of GitHub contributions, which can be done with: + - 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 + python tools/github_stats.py --milestone $MILESTONE > stats.rst - which may need some manual cleanup. Add the cleaned up result and add it to `docs/source/whatsnew/github-stats-X.rst` (make a new file, or add it to the top, depending on whether it is a major release). - You can use: + 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. - git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f +To find duplicates and update `.mailmap`, use: - to find duplicates and update `.mailmap`. - Before generating the GitHub stats, verify that all closed issues and pull requests [have appropriate milestones](https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones). [This search](https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue) should return no results. + git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f -# 2. Run the `tools/build_release` script -This does all the file checking and building that the real release script will do. -This will let you do test installations, check that the build procedure runs OK, etc. -You may want to also do a test build of the docs. +#. Run the `tools/build_release` script +--------------------------------------- -# 3. Create and push the new tag +This 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. + +#. Create and push the new tag +------------------------------ Edit `IPython/core/release.py` to have the current version. @@ -64,36 +92,51 @@ Update release.py back to `x.y-dev` or `x.y-maint`, and push: git commit -am "back to development" git push origin $BRANCH -# 4. Get a fresh clone of the tag for building the release: +#. Get a fresh clone +-------------------- - cd /tmp - git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG" +Get a fresh clone of the tag for building the release: -# 5. Run the `release` script + cd /tmp + git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG" - cd tools && ./release +#. Run the release script +------------------------- -This makes the tarballs, zipfiles, and wheels. It posts them to archive.ipython.org and -registers the release with PyPI. +Run the `release` script:: -This will require that you have current wheel, Python 3.4 and Python 2.7. + cd tools && ./release -# 7. Update the IPython website +This makes the tarballs, zipfiles, and wheels. It posts +them to archive.ipython.org and registers the release with PyPI. -- release announcement (news, announcements) -- update current version and download links -- (If major release) update links on the documentation page +This step requires having a current wheel, Python 3.4 and Python 2.7. -# 8. Drafting a short release announcement +#. Draft a short release announcement +------------------------------------- This should include i) highlights and ii) a link to the html version of the *What's new* section of the documentation. -Post to mailing list, and link from Twitter. +Post the announcement to the mailing list, and link from Twitter. + +#. Update milestones on GitHub +------------------------------ + +- close the just released milestone +- open a new milestone for the next release (x, y+1), if the milestone doesn't + exist already + +#. 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) -# 9. Update milestones on GitHub +#. Celebrate! +------------- -- close the milestone you just released -- open new milestone for (x, y+1), if it doesn't exist already +Celebrate the release and thank the contributors for their work. -# 10. Celebrate! diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 42bd327..e346b84 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -5,9 +5,9 @@ Developer's guide for Third Party Tools and Libraries ===================================================== .. important: - + This guide contains information for developers of third party tools and - libraries that use IPython. Documentation for developers of core + libraries that use IPython. Documentation for developers of co *IPython itself* can be found in the :doc:`coredev/index`. .. toctree:: @@ -24,7 +24,7 @@ Developer's guide for Third Party Tools and Libraries Making an IPython release ========================= -Make sure the repository is clean of any file that could be problematic. +Make sure the repository is clean of any file that could be problematic. You can remove all non-tracked files with: .. code:: 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