update release process

docs/source/coredev/index.rst

@@ -1,321 +1,322 b''
 .. _core_developer_guide:
 
 =================================
 Guide for IPython core Developers
 =================================
 
 This guide documents the development of IPython itself.  Alternatively,
 developers of third party tools and libraries that use IPython should see the
 :doc:`../development/index`.
 
 
 For instructions on how to make a developer install see :ref:`devinstall`.
 
 Backporting Pull requests
 -------------------------
 
 All pull requests should usually be made against ``master``, if a Pull Request
 need to be backported to an earlier release; then it should be tagged with the
 correct ``milestone``.
 
 If you tag a pull request with a milestone **before** merging the pull request,
-and the base ref is `master`, then our backport bot should automatically create
+and the base ref is ``master``, then our backport bot should automatically create
 a corresponding pull-request that backport on the correct branch.
 
-If you are an admin on the IPython repository you can also just mention the
+If you have write access to the IPython repository you can also just mention the
 **backport bot** to do the work for you. The bot is evolving so instructions may
 be different. At the time of this writing you can use::
 
-    @meeseeksdev[bot] backport [to <branchname>]
+    @meeseeksdev[bot] backport [to] <branchname>
 
 The bot will attempt to backport the current pull-request and issue a PR if
-possible. If the milestone is set on the issue you can omit the branch to
-backport to.
+possible. 
 
 .. note::
 
     The ``@`` and ``[bot]`` when mentioning the bot should be optional and can
     be omitted.
 
 If the pull request cannot be automatically backported, the bot should tell you
 so on the PR and apply a "Need manual backport" tag to the origin PR.
 
 
 Backport with ghpro
 -------------------
 
 We can also use `ghpro <https://pypi.python.org/pypi/ghpro>`_
 to automatically list and apply the PR on other branches. For example:
 
 .. code-block:: bash
     
     $ backport-pr todo --milestone 5.2
     [...snip..]
     The following PRs have been backported
     9848
     9851
     9953
     9955
     The following PRs should be backported:
     9417
     9863
     9925
     9947
 
     $ backport-pr apply 5.x 9947
     [...snip...]
 
 
 .. _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.
 
 During the release process, you might need the extra following dependencies:
 
  - ``keyring`` to access your GitHub authentication tokens
  - ``graphviz`` to generate some graphs in the documentation
  - ``ghpro`` to generate the stats
 
 Make sure you have all the required dependencies to run the tests as well.
 
 
 1. Set Environment variables
 ----------------------------
 
 Set environment variables to document previous release tag, current
 release milestone, current release version, and git tag.
 
 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`` them. The format for bash is as follows, but note that these values
 are just an example valid only for the 5.0 release; you'll need to update them
 for the release you are actually making::
 
     PREV_RELEASE=4.2.1
     MILESTONE=5.0
     VERSION=5.0.0
     BRANCH=master
 
 
 2. Create GitHub stats and finish release note
 ----------------------------------------------
 
 .. note::
 
     This step is optional if making a Beta or RC release.
 
 .. note::
 
     Before generating the GitHub stats, verify that all closed issues and pull
     requests have `appropriate milestones
     <https://github.com/ipython/ipython/wiki/Dev:-GitHub-workflow#milestones>`_.
     `This search
     <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
     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 (don't forget to add it to
       the git repository as well). 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.
 
     - Edit ``docs/source/whatsnew/index.rst`` to list the new ``github-stats-X``
       file you just created.
 
-    - Remove temporarily the first entry called ``development`` (you'll need to
-      add it back after release).
+    - You do not need to temporarily remove the first entry called
+      ``development``, nor re-add it after the release, it will automatically be
+      hidden when releasing a stable version of IPython (if ``_version_extra``
+      in ``release.py`` is an empty string.
 
       Make sure that the stats file has a header or it won't be rendered in
       the final documentation.
 
 To find duplicates and update `.mailmap`, use::
 
     git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
 
 If a minor release you might need to do some of the above points manually, and
 forward port the changes.
 
 3. 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.
 
 
 4. Update the release version number
 ------------------------------------
 
 Edit ``IPython/core/release.py`` to have the current version.
 
 in particular, update version number and ``_version_extra`` content in
 ``IPython/core/release.py``.
 
 Step 5 will validate your changes automatically, but you might still want to
 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'. Check the environment variable
 ``$VERSION`` as well.
 
 You will likely just have to modify/comment/uncomment one of the lines setting
 ``_version_extra``
 
 
 5. 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.
 
 The ``build_release`` script will in particular verify that the version number
 match PEP 440, in order to avoid surprise at the time of build upload.
 
 We encourage creating a test build of the docs as well.
 
 6. Create and push the new tag
 ------------------------------
 
 Commit the changes to release.py::
 
     git commit -am "release $VERSION"
     git push origin $BRANCH
 
 Create and push the tag::
 
     git tag -am "release $VERSION" "$VERSION"
     git push origin --tags
 
 Update release.py back to ``x.y-dev`` or ``x.y-maint``, and re-add the
 ``development`` entry in ``docs/source/whatsnew/index.rst`` and push::
 
     git commit -am "back to development"
     git push origin $BRANCH
 
 Now checkout the tag we just made::
 
     git checkout $VERSION
 
 7. Run the release script
 -------------------------
 
 Run the ``release`` script, this step requires having a current wheel, Python
 >=3.4 and Python 2.7.::
 
     ./tools/release
 
 This makes the tarballs and wheels, and puts them under the ``dist/``
 folder. Be sure to test the ``wheels``  and the ``sdist`` locally before
 uploading them to PyPI. We do not use an universal wheel as each wheel
 installs an ``ipython2`` or ``ipython3`` script, depending on the version of
 Python it is built for. Using an universal wheel would prevent this.
 
 Use the following to actually upload the result of the build::
 
     ./tools/release upload
 
 It should posts them to ``archive.ipython.org`` and to PyPI.
 
 PyPI/Warehouse will automatically hide previous releases. If you are uploading
 a non-stable version, make sure to log-in to PyPI and un-hide previous version.
 
 
 8. 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 or blog, and link from Twitter.
 
 .. note::
 
     If you are doing a RC or Beta, you can likely skip the next steps.
 
 9. 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
 
 10. 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)
 
 11. Update readthedocs
 ----------------------
 
 Make sure to update readthedocs and set the latest tag as stable, as well as
 checking that previous release is still building under its own tag.
 
 12. Update the Conda-Forge feedstock
 ------------------------------------
 
 Follow the instructions on `the repository <https://github.com/conda-forge/ipython-feedstock>`_
 
 13. Celebrate!
 --------------
 
 Celebrate the release and please thank the contributors for their work. Great
 job!
 
 
 
 Old Documentation
 =================
 
 Out of date documentation is still available and have been kept for archival purposes.
 
 .. note::
 
   Developers documentation used to be on the IPython wiki, but are now out of
   date. The wiki is though still available for historical reasons: `Old IPython
   GitHub Wiki.  <https://github.com/ipython/ipython/wiki/Dev:-Index>`_

docs/source/whatsnew/index.rst

@@ -1,46 +1,62 b''
 .. Developers should add in this file, during each release cycle, information
 .. about important changes they've made, in a summary format that's meant for
 .. end users.  For each release we normally have three sections: features,  bug
 .. fixes and api breakage.
 .. Please remember to credit the authors of the contributions by name,
 .. especially when they are new users or developers who do not regularly
 .. participate  in IPython's development.
 
 .. _whatsnew_index:
 
 =====================
 What's new in IPython
 =====================
 
+.. this will appear in the docs if we are nto releasing a versin (ie is
+.. _version_extra in release.py is empty stringA
+
+.. only:: ipydev
+
+   Developpement version in-progress features:
+   
+   .. toctree::
+      development
+
+.. this make a hidden toctree that avoid sphinx to complain about documents
+.. included nowhere when building docs for stable
+.. only:: ipystable
+   .. toctree::
+      :hidden:
+      development
+
 This section documents the changes that have been made in various versions of
 IPython. Users should consult these pages to learn about new features, bug
 fixes and backwards incompatibilities. Developers should summarize the
 development work they do here in a user friendly format.
 
 .. toctree::
    :maxdepth: 1
 
-   development
    version7
    version6
    github-stats-6
    version5
    github-stats-5
    version4
    github-stats-4
    version3
    github-stats-3
    version3_widget_migration
    version2.0
    github-stats-2.0
    version1.0
    github-stats-1.0
    version0.13
    github-stats-0.13
    version0.12
    github-stats-0.12
    version0.11
    github-stats-0.11
    version0.10
    version0.9
    version0.8

docs/source/whatsnew/version7.rst

@@ -1,214 +1,215 b''
 ============
  7.x Series
 ============
 
 .. _whatsnew700:
 
 IPython 7.0.0
 =============
 
 .. warning::
 
    IPython 7.0 is currently in Beta, Feedback on API/changes and
    addition/updates to this cahngelog are welcomed.
 
 Released .... ...., 2017
 
 IPython 7 include major features improvement as you can read in the following
 changelog. This is also the second major version of IPython to stop support only
 Python 3 – starting at Python 3.4. Python 2 is still still community supported
 on the bugfix only 5.x branch, but we remind you that Python 2 EOL is Jan 1st
 2020.
 
 We were able to backport bug fixes to the 5.x branch thanks to our backport bot which
 backported more than `70 Pull-Requests
-<https://github.com/ipython/ipython/pulls?page=3&q=is%3Apr+sort%3Aupdated-desc+author%3Aapp%2Fmeeseeksdev++5.x&utf8=%E2%9C%93>`_, but there are still many PRs that required manually work, and this is an area of the project were you can easily contribute by looking for `PRs still needed backport<https://github.com/ipython/ipython/issues?q=label%3A%22Still+Needs+Manual+Backport%22+is%3Aclosed+sort%3Aupdated-desc>`_
+<https://github.com/ipython/ipython/pulls?page=3&q=is%3Apr+sort%3Aupdated-desc+author%3Aapp%2Fmeeseeksdev++5.x&utf8=%E2%9C%93>`_, but there are still many PRs that required manually work, and this is an area of the project were you can easily contribute by looking for `PRs still needed backport <https://github.com/ipython/ipython/issues?q=label%3A%22Still+Needs+Manual+Backport%22+is%3Aclosed+sort%3Aupdated-desc>`_
 
 IPython 6.x branch will likely not see any further release unless we critical
 bugs are found.
 
 Make sure you have pip > 9.0 before upgrading. You should be able to update by simply runngin
 
 .. code::
 
     pip install ipython --upgrade
 
 Or if you have conda installed: 
 
 .. code::
    
    conda install ipython
 
 
 
 Prompt Toolkit 2.0
 ------------------
 
 IPython 7.0+ now use ``prompt_toolkit 2.0``, if you still need to use earlier 
 ``prompt_toolkit`` version you may need to pin IPython to ``<7.0``.
 
 Autowait: Asynchronous REPL
 ---------------------------
 
 Staring with IPython 7.0 and on Python 3.6+, IPython can automatically await
 code at top level, you should not need to access an event loop or runner
 yourself. To know more read the :ref:`autoawait` section of our docs, see
 :ghpull:`11265` or try the following code::
 
     Python 3.6.0
     Type 'copyright', 'credits' or 'license' for more information
     IPython 7.0.0 -- An enhanced Interactive Python. Type '?' for help.
 
     In [1]: import aiohttp
        ...: result = aiohttp.get('https://api.github.com')
 
     In [2]: response = await result
     <pause for a few 100s ms>
 
     In [3]: await response.json()
     Out[3]:
     {'authorizations_url': 'https://api.github.com/authorizations',
      'code_search_url': 'https://api.github.com/search/code?q={query}{&page,per_page,sort,order}',
     ...
     }
 
 .. note::
 
    Async integration is experimental code, behavior may change or be removed
    between Python and IPython versions without warnings.
 
 Integration is by default with `asyncio`, but other libraries can be configured,
 like ``curio`` or ``trio``, to improve concurrency in the REPL::
 
     In [1]: %autoawait trio
 
     In [2]: import trio
 
     In [3]: async def child(i):
        ...:     print("   child %s goes to sleep"%i)
        ...:     await trio.sleep(2)
        ...:     print("   child %s wakes up"%i)
 
     In [4]: print('parent start')
        ...: async with trio.open_nursery() as n:
        ...:     for i in range(3):
        ...:         n.spawn(child, i)
        ...: print('parent end')
     parent start
        child 2 goes to sleep
        child 0 goes to sleep
        child 1 goes to sleep
        <about 2 seconds pause>
        child 2 wakes up
        child 1 wakes up
        child 0 wakes up
     parent end
 
 See :ref:`autoawait` for more information.
 
 
 Asynchronous code in a Notebook interface or any other frontend using the
 Jupyter Protocol will need further updates of the IPykernel package.
 
 Non-Asynchronous code
 ~~~~~~~~~~~~~~~~~~~~~
 
 As the internal API of IPython are now asynchronous, IPython need to run under
 an even loop. In order to allow many workflow, (like using the ``%run`` magic,
 or copy_pasting code that explicitly starts/stop event loop), when top-level code
 is detected as not being asynchronous, IPython code is advanced via a
 pseudo-synchronous runner, and will not may not advance pending tasks.
 
 Change to Nested Embed
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The introduction of the ability to run async code had some effect on the
 ``IPython.embed()`` API. By default embed will not allow you to run asynchronous
 code unless a event loop is specified.
 
 Effects on Magics
 ~~~~~~~~~~~~~~~~~
 
 Some magics will not work with Async, and will need updates. Contribution
 welcome.
 
 Expected Future changes
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 We expect more internal but public IPython function to become ``async``, and
 will likely end up having a persisting event loop while IPython is running.
 
 Thanks
 ~~~~~~
 
 This took more than a year in the making, and the code was rebased a number of
 time leading to commit authorship that may have been lost in the final
 Pull-Request. Huge thanks to many people for contribution, discussion, code,
 documentation, use-case: dalejung, danielballan, ellisonbg, fperez, gnestor,
 minrk, njsmith, pganssle, tacaswell, takluyver , vidartf ... And many other.
 
 
 Autoreload Improvment
 ---------------------
 
 The magic ``%autoreload 2`` now captures new methods added to classes. Earlier, only methods existing as of the initial import were being tracked and updated.  
 
 This new feature helps dual environment development - Jupyter+IDE - where the code gradually moves from notebook cells to package files, as it gets structured.
 
 **Example**: An instance of the class `MyClass` will be able to access the method `cube()` after it is uncommented and the file `file1.py` saved on disk.
 
 
 ..code::
 
    # notebook
 
    from mymodule import MyClass
    first = MyClass(5)
 
 .. code::
+
    # mymodule/file1.py
 
    class MyClass:
 
        def __init__(self, a=10):
            self.a = a
 
        def square(self):
            print('compute square')
            return self.a*self.a
 
        # def cube(self):
        #     print('compute cube')
        #     return self.a*self.a*self.a
 
 
 
 
 Misc
 ----
 
 The autoindent feature that was deprecated in 5.x was re-enabled and
 un-deprecated in :ghpull:`11257`
 
 Make ``%run -n -i ...`` work correctly. Earlier, if ``%run`` was passed both arguments, ``-n`` would be silently ignored. See :ghpull:`10308`
 
 
 
 
 
 Deprecations
 ------------
 
 A couple of unused function and methods have been deprecated and will be removed
 in future versions:
 
   - ``IPython.utils.io.raw_print_err``
   - ``IPython.utils.io.raw_print``
 
   
 Backwards incompatible changes
 ------------------------------
 
 * The API for transforming input before it is parsed as Python code has been
   completely redesigned, and any custom input transformations will need to be
   rewritten. See :doc:`/config/inputtransforms` for details of the new API.