From 8e7473017f27caa060cd68418ec5d833b99ee1de 2016-01-28 23:22:20 From: Carol Willing Date: 2016-01-28 23:22:20 Subject: [PATCH] Fix up rst formatting --- diff --git a/docs/source/coredev/index.rst b/docs/source/coredev/index.rst index 306b8cc..69c70c6 100644 --- a/docs/source/coredev/index.rst +++ b/docs/source/coredev/index.rst @@ -1,15 +1,15 @@ .. _core_developer_guide: ================================== -Developer's guide for core IPython +Developer's guide to 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`. +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 IPython itself should also consult the -`developer information `_ +Developers working on core IPython should also consult the +`developer information `_ on the IPython GitHub wiki. .. toctree:: diff --git a/docs/source/coredev/old_release_doc.rst b/docs/source/coredev/old_release_doc.rst index 480cc96..3040497 100644 --- a/docs/source/coredev/old_release_doc.rst +++ b/docs/source/coredev/old_release_doc.rst @@ -1,7 +1,7 @@ .. old_release_doc:: -Making an IPython release [TODO:: Can this be replaced by the Release Process document???] -========================================================================================== +Making an IPython release [TODO:: Can this content by removed ???] +================================================================== Make sure the repository is clean of any file that could be problematic. You can remove all non-tracked files with: diff --git a/docs/source/coredev/release_process.rst b/docs/source/coredev/release_process.rst index c6e312f..6a3e0e9 100644 --- a/docs/source/coredev/release_process.rst +++ b/docs/source/coredev/release_process.rst @@ -10,11 +10,11 @@ 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 +1. Set Environment variables ---------------------------- Set environment variables to document previous release tag, current -release milestone, current release version, and git tag: +release milestone, current release version, and git tag:: PREV_RELEASE=rel-1.0.0 MILESTONE=1.1 @@ -27,13 +27,13 @@ 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 ------------------------ +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 `_. + pull requests have `appropriate milestones `_. `This search `_ should return no results before creating the GitHub stats. @@ -58,49 +58,49 @@ If a major release: 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: +To find duplicates and update `.mailmap`, use:: git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f -#. Run the `tools/build_release` script +3. Run the `tools/build_release` script --------------------------------------- -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. +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. -#. Create and push the new tag +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: +Commit the changes to release.py and jsversion:: git commit -am "release $VERSION" git push origin $BRANCH -Create and push the tag: +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: +Update release.py back to `x.y-dev` or `x.y-maint`, and push:: git commit -am "back to development" git push origin $BRANCH -#. Get a fresh clone +5. Get a fresh clone -------------------- -Get a fresh clone of the tag for building the release: +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" -#. Run the release script +6. Run the release script ------------------------- Run the `release` script:: @@ -112,31 +112,38 @@ 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. -#. Draft a short release announcement +7. 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. +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. -#. Update milestones on GitHub +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 -#. Update the IPython website +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) -#. Celebrate! -------------- +10. Celebrate! +-------------- -Celebrate the release and thank the contributors for their work. +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 e346b84..a945625 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -1,14 +1,14 @@ .. _developer_guide: ===================================================== -Developer's guide for Third Party Tools and Libraries +Developer's guide for third party tools and libraries ===================================================== -.. important: +.. important:: This guide contains information for developers of third party tools and - libraries that use IPython. Documentation for developers of co - *IPython itself* can be found in the :doc:`coredev/index`. + libraries that use IPython. Alternatively, documentation for core + **IPython** development can be found in the :doc:`../coredev/index`. .. toctree:: :maxdepth: 1 @@ -19,53 +19,4 @@ Developer's guide for Third Party Tools and Libraries 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