From 86151b821f5a0ad3d6a9245779174bf57dbdffd2 2016-01-28 17:36:57 From: Carol Willing Date: 2016-01-28 17:36:57 Subject: [PATCH] Add a core dev section to docs --- diff --git a/docs/source/coredev/index.rst b/docs/source/coredev/index.rst new file mode 100644 index 0000000..3d5445c --- /dev/null +++ b/docs/source/coredev/index.rst @@ -0,0 +1,67 @@ +.. _core_developer_guide: + +================================== +Developer's guide for core IPython +================================== + +This guide documents the development of core *IPython itself*. Developers of +third party tools and libraries that use IPython should see the +:doc:`development/index` at `Developer's guide for Third Party Tools and Libraries`. + +Developers working on IPython itself should also consult the +`developer information `_ +on the IPython GitHub wiki. + +.. toctree:: + :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``. + diff --git a/docs/source/coredev/release_process.rst b/docs/source/coredev/release_process.rst new file mode 100644 index 0000000..f45b7a7 --- /dev/null +++ b/docs/source/coredev/release_process.rst @@ -0,0 +1,99 @@ +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. + +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. + +# 0. Environment variables + +You can set some env variables to note previous release tag and current release milestone, version, and git tag: + + PREV_RELEASE=rel-1.0.0 + MILESTONE=1.1 + VERSION=1.1.0 + 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`). + +# 1. Finish release notes + +- 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 points. + - move the contents of `development.rst` to `versionX.rst` +- 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. 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: + + git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f + + 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. + +# 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. + +# 3. 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 + +# 4. 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" + +# 5. 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 will require that you have current wheel, Python 3.4 and Python 2.7. + +# 7. Update the IPython website + +- release announcement (news, announcements) +- update current version and download links +- (If major release) update links on the documentation page + +# 8. Drafting 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. + +# 9. Update milestones on GitHub + +- close the milestone you just released +- open new milestone for (x, y+1), if it doesn't exist already + +# 10. Celebrate! diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 2553d22..42bd327 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -1,20 +1,14 @@ .. _developer_guide: -========================= -IPython developer's guide -========================= - -This are two categories of developer focused documentation: - -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. +===================================================== +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 + *IPython itself* can be found in the :doc:`coredev/index`. .. toctree:: :maxdepth: 1