1=============== 2Release process 3=============== 4 5.. _`Release Cadence`: 6 7Release Cadence 8=============== 9 10The pip project has a release cadence of releasing whatever is on ``master`` 11every 3 months. This gives users a predictable pattern for when releases 12are going to happen and prevents locking up improvements for fixes for long 13periods of time, while still preventing massively fracturing the user base 14with version numbers. 15 16Our release months are January, April, July, October. The release date within 17that month will be up to the release manager for that release. If there are 18no changes, then that release month is skipped and the next release will be 193 months later. 20 21The release manager may, at their discretion, choose whether or not there 22will be a pre-release period for a release, and if there is may extend that 23period into the next month if needed. 24 25Because releases are made direct from the ``master`` branch, it is essential 26that ``master`` is always in a releasable state. It is acceptable to merge 27PRs that partially implement a new feature, but only if the partially 28implemented version is usable in that state (for example, with reduced 29functionality or disabled by default). In the case where a merged PR is found 30to need extra work before being released, the release manager always has the 31option to back out the partial change prior to a release. The PR can then be 32reworked and resubmitted for the next release. 33 34.. _`Deprecation Policy`: 35 36Deprecation Policy 37================== 38 39Any change to pip that removes or significantly alters user-visible behavior 40that is described in the pip documentation will be deprecated for a minimum of 416 months before the change occurs. 42 43Certain changes may be fast tracked and have a deprecation period of 3 months. 44This requires at least two members of the pip team to be in favor of doing so, 45and no pip maintainers opposing. 46 47Deprecation will take the form of a warning being issued by pip when the 48feature is used. Longer deprecation periods, or deprecation warnings for 49behavior changes that would not normally be covered by this policy, are also 50possible depending on circumstances, but this is at the discretion of the pip 51maintainers. 52 53Note that the documentation is the sole reference for what counts as agreed 54behavior. If something isn't explicitly mentioned in the documentation, it can 55be changed without warning, or any deprecation period, in a pip release. 56However, we are aware that the documentation isn't always complete - PRs that 57document existing behavior with the intention of covering that behavior with 58the above deprecation process are always acceptable, and will be considered on 59their merits. 60 61.. note:: 62 63 pip has a helper function for making deprecation easier for pip maintainers. 64 The supporting documentation can be found in the source code of 65 ``pip._internal.utils.deprecation.deprecated``. The function is not a part of 66 pip's public API. 67 68.. _`Python 2 Support`: 69 70Python 2 Support 71---------------- 72 73pip will continue to ensure that it runs on Python 2.7 after the `CPython 2.7 74EOL date`_. Support for Python 2.7 will be dropped, if bugs in Python 2.7 itself 75make this necessary (which is unlikely) or in pip 21.0 (Jan 2021), whichever is 76earlier. 77 78However, bugs reported with pip which only occur on Python 2.7 would likely not 79be addressed directly by pip's maintainers. Pull Requests to fix Python 2.7 80only bugs will be considered, and merged (subject to normal review processes). 81Note that there may be delays due to the lack of developer resources for 82reviewing such pull requests. 83 84Python Support Policy 85--------------------- 86 87In general, a given Python version is supported until its usage on PyPI falls below 5%. 88This is at the maintainers' discretion, in case extraordinary circumstances arise. 89 90.. _`Feature Flags`: 91 92Feature Flags 93============= 94 95``--use-deprecated`` 96-------------------- 97 98Example: ``--use-deprecated=legacy-resolver`` 99 100Use for features that will be deprecated. Deprecated features should remain 101available behind this flag for at least six months, as per the deprecation 102policy. 103 104Features moved behind this flag should always include a warning that indicates 105when the feature is scheduled to be removed. 106 107Once the feature is removed, users who use the flag should be shown an error. 108 109``--use-feature`` 110----------------- 111 112Example: ``--use-feature=2020-resolver`` 113 114Use for new features that users can test before they become pip's default 115behaviour (e.g. alpha or beta releases). 116 117Once the feature becomes the default behaviour, this flag can remain in place, 118but should issue a warning telling the user that it is no longer necessary. 119 120Release Process 121=============== 122 123Creating a new release 124---------------------- 125 126#. Checkout the current pip ``master`` branch. 127#. Ensure you have the latest ``nox`` installed. 128#. Prepare for release using ``nox -s prepare-release -- YY.N``. 129 This will update the relevant files and tag the correct commit. 130#. Build the release artifacts using ``nox -s build-release -- YY.N``. 131 This will checkout the tag, generate the distribution files to be 132 uploaded and checkout the master branch again. 133#. Upload the release to PyPI using ``nox -s upload-release -- YY.N``. 134#. Push all of the changes including the tag. 135#. Regenerate the ``get-pip.py`` script in the `get-pip repository`_ (as 136 documented there) and commit the results. 137#. Submit a Pull Request to `CPython`_ adding the new version of pip (and upgrading 138 setuptools) to ``Lib/ensurepip/_bundled``, removing the existing version, and 139 adjusting the versions listed in ``Lib/ensurepip/__init__.py``. 140 141 142.. note:: 143 144 If the release dropped the support of an obsolete Python version ``M.m``, 145 a new ``M.m/get-pip.py`` needs to be published: update the ``all`` task from 146 ``tasks/generate.py`` in `get-pip repository`_ and make a pull request to 147 `psf-salt repository`_ to add the new ``get-pip.py`` (and its directory) to 148 ``salt/pypa/bootstrap/init.sls``. 149 150 151.. note:: 152 153 If the ``get-pip.py`` script needs to be updated due to changes in pip internals 154 and if the last ``M.m/get-pip.py`` published still uses the default template, make 155 sure to first duplicate ``templates/default.py`` as ``templates/pre-YY.N.py`` 156 before updating it and specify in ``tasks/generate.py`` that ``M.m/get-pip.py`` 157 now needs to use ``templates/pre-YY.N.py``. 158 159 160Creating a bug-fix release 161-------------------------- 162 163Sometimes we need to release a bugfix release of the form ``YY.N.Z+1``. In 164order to create one of these the changes should already be merged into the 165``master`` branch. 166 167#. Create a new ``release/YY.N.Z+1`` branch off of the ``YY.N`` tag using the 168 command ``git checkout -b release/YY.N.Z+1 YY.N``. 169#. Cherry pick the fixed commits off of the ``master`` branch, fixing any 170 conflicts. 171#. Run ``nox -s prepare-release -- YY.N.Z+1``. 172#. Merge master into your release branch and drop the news files that have been 173 included in your release (otherwise they would also appear in the ``YY.N+1`` 174 changelog) 175#. Push the ``release/YY.N.Z+1`` branch to github and submit a PR for it against 176 the ``master`` branch and wait for the tests to run. 177#. Once tests run, merge the ``release/YY.N.Z+1`` branch into master, and follow 178 the above release process starting with step 4. 179 180.. _`get-pip repository`: https://github.com/pypa/get-pip 181.. _`psf-salt repository`: https://github.com/python/psf-salt 182.. _`CPython`: https://github.com/python/cpython 183.. _`CPython 2.7 EOL date`: https://www.python.org/doc/sunset-python-2/ 184