diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a556ac0467b..ada7086d923 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,5 +6,5 @@ require either a news file fragment or a marker to indicate they don't require one. To read more about adding a news file fragment for your PR, please check out -our documentation at: https://pip.pypa.io/en/latest/development/#adding-a-news-entry +our documentation at: https://pip.pypa.io/en/latest/development/contributing/#adding-a-news-entry --> diff --git a/docs/conf.py b/docs/conf.py index 0d7ce04a3be..5e48423412b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -127,6 +127,7 @@ extlinks = { 'issue': ('https://github.com/pypa/pip/issues/%s', '#'), 'pull': ('https://github.com/pypa/pip/pull/%s', 'PR #'), + 'pypi': ('https://pypi.org/project/%s', ''), } # -- Options for HTML output -------------------------------------------------- diff --git a/docs/development.rst b/docs/development.rst deleted file mode 100644 index 5b1ad13701b..00000000000 --- a/docs/development.rst +++ /dev/null @@ -1,271 +0,0 @@ -=========== -Development -=========== - -Pull Requests -============= - -- Submit Pull Requests against the `master` branch. -- Provide a good description of what you're doing and why. -- Provide tests that cover your changes and try to run the tests locally first. - -**Example**. Assuming you set up GitHub account, forked pip repository from -https://github.com/pypa/pip to your own page via web interface, and your -fork is located at https://github.com/yourname/pip - -:: - - $ git clone git@github.com:pypa/pip.git - $ cd pip - # ... - $ git diff - $ git add ... - $ git status - $ git commit - -You may reference relevant issues in commit messages (like #1259) to -make GitHub link issues and commits together, and with phrase like -"fixes #1259" you can even close relevant issues automatically. Now -push the changes to your fork:: - - $ git push git@github.com:yourname/pip.git - -Open Pull Requests page at https://github.com/yourname/pip/pulls and -click "New pull request" and select your fork. That's it. - -Pull requests should be self-contained, and limited in scope. Before being -merged, a pull request must be reviewed, and keeping individual PRs limited -in scope makes this far easier. In particular, pull requests must not be -treated as "feature branches", with ongoing development work happening -within the PR. Instead, the feature should be broken up into smaller, -independent parts which can be reviewed and merged individually. - -When creating a pull request, avoid including "cosmetic" changes to -code that is unrelated to your change, as these make reviewing the PR -more difficult. Examples include re-flowing text in comments or -documentation, or addition or removal of blank lines or whitespace -within lines. Such changes can be made separately, as a "formatting -cleanup" PR, if needed. - - -Automated Testing -================= - -All pull requests and merges to 'master' branch are tested using `Travis CI`_ -and `Appveyor CI`_ based on our `.travis.yml`_ and `appveyor.yml`_ files. - -You can find the status and results to the CI runs for your PR on GitHub's Web -UI for the pull request. You can also find links to the CI services' pages for -the specific builds in the form of "Details" links, in case the CI run fails -and you wish to view the output. - -To trigger CI to run again for a pull request, you can close and open the pull -request or submit another change to the pull request. If needed, project -maintainers can manually trigger a restart of a job/build. - -Running tests -============= - -OS Requirements: subversion, bazaar, git, and mercurial. - -Python Requirements: tox or install all packages listed in -`tools/tests-requirements.txt`_ - -Ways to run the tests locally:: - - $ tox -e py36 # The preferred way to run the tests, can use pyNN to - # run for a particular version or leave off the -e to - # run for all versions. - $ python setup.py test # Using the setuptools test plugin - $ py.test # Using py.test directly - $ tox # Using tox against pip's tox.ini - -If you are missing one of the VCS tools, you can tell ``py.test`` to skip it:: - - # When using tox - $ tox -e py36 -- -k 'not svn' - $ tox -e py36 -- -k 'not (svn or git)' - # Directly with py.test - $ py.test -k 'not svn' - $ py.test -k 'not (svn or git)' - - -Getting Involved -================ - -The pip project welcomes help in the following ways: - -- Making Pull Requests for code, tests, or docs. -- Commenting on open issues and pull requests. -- Helping to answer questions on the `mailing list`_. - -If you want to become an official maintainer, start by helping out. - -Later, when you think you're ready, get in touch with one of the maintainers, -and they will initiate a vote. - - -Adding a NEWS Entry -=================== - -The ``NEWS.rst`` file is managed using `towncrier`_ and all non trivial changes -must be accompanied by a news entry. - -To add an entry to the news file, first you need to have created an issue -describing the change you want to make. A Pull Request itself *may* function as -such, but it is preferred to have a dedicated issue (for example, in case the -PR ends up rejected due to code quality reasons). - -Once you have an issue or pull request, you take the number and you create a -file inside of the ``news/`` directory named after that issue number with an -extension of ``removal``, ``feature``, ``bugfix``, or ``doc``. Thus if your -issue or PR number is ``1234`` and this change is fixing a bug, then you would -create a file ``news/1234.bugfix``. PRs can span multiple categories by creating -multiple files (for instance, if you added a feature and deprecated/removed the -old feature at the same time, you would create ``news/NNNN.feature`` and -``news/NNNN.removal``). Likewise if a PR touches multiple issues/PRs you may -create a file for each of them with the exact same contents and Towncrier will -deduplicate them. - -The contents of this file are reStructuredText formatted text that will be used -as the content of the news file entry. You do not need to reference the issue -or PR numbers here as towncrier will automatically add a reference to all of -the affected issues when rendering the news file. - -In order to maintain a consistent style in the ``NEWS.rst`` file, it is -preferred to keep the news entry to the point, in sentence case, shorter than -80 characters and in an imperative tone -- an entry should complete the sentence -"This change will ...". In rare cases, where one line is not enough, use a -summary line in an imperative tone followed by a blank line separating it -from a description of the feature/change in one or more paragraphs, each wrapped -at 80 characters. Remember that a news entry is meant for end users and should -only contain details relevant to an end user. - -A trivial change is anything that does not warrant an entry in the news file. -Some examples are: Code refactors that don't change anything as far as the -public is concerned, typo fixes, white space modification, etc. To mark a PR -as trivial a contributor simply needs to add a randomly named, empty file to -the ``news/`` directory with the extension of ``.trivial``. If you are on a -POSIX like operating system, one can be added by running -``touch news/$(uuidgen).trivial``. On Windows, the same result can be achieved -in Powershell using ``New-Item "news/$([guid]::NewGuid()).trivial"``. Core -committers may also add a "trivial" label to the PR which will accomplish the -same thing. - -Upgrading, removing, or adding a new vendored library gets a special mention -using a ``news/.vendor`` file. This is in addition to any features, -bugfixes, or other kinds of news that pulling in this library may have. This -uses the library name as the key so that updating the same library twice doesn't -produce two news file entries. - -Changes to the processes, policies, or other non code related changed that are -otherwise notable can be done using a ``news/.process`` file. This is not -typically used, but can be used for things like changing version schemes, -updating deprecation policy, etc. - - -Release Cadence -=============== - -The pip project has a release cadence of releasing whatever is on ``master`` -every 3 months. This gives users a predictable pattern for when releases -are going to happen and prevents locking up improvements for fixes for long -periods of time, while still preventing massively fracturing the user base -with version numbers. - -Our release months are January, April, July, October. The release date within -that month will be up to the release manager for that release. If there are -no changes, then that release month is skipped and the next release will be -3 month later. - -The release manager may, at their discretion, choose whether or not there -will be a pre-release period for a release, and if there is may extend that -period into the next month if needed. - -Because releases are made direct from the ``master`` branch, it is essential -that ``master`` is always in a releasable state. It is acceptable to merge -PRs that partially implement a new feature, but only if the partially -implemented version is usable in that state (for example, with reduced -functionality or disabled by default). In the case where a merged PR is found -to need extra work before being released, the release manager always has the -option to back out the partial change prior to a release. The PR can then be -reworked and resubmitted for the next release. - - -Deprecation Policy -================== - -Any change to pip that removes or significantly alters user-visible behavior -that is described in the pip documentation will be deprecated for a minimum of -6 months before the change occurs. Deprecation will take the form of a warning -being issued by pip when the feature is used. Longer deprecation periods, or -deprecation warnings for behavior changes that would not normally be covered by -this policy, are also possible depending on circumstances, but this is at the -discretion of the pip developers. - -Note that the documentation is the sole reference for what counts as agreed -behavior. If something isn't explicitly mentioned in the documentation, it can -be changed without warning, or any deprecation period, in a pip release. -However, we are aware that the documentation isn't always complete - PRs that -document existing behavior with the intention of covering that behavior with -the above deprecation process are always acceptable, and will be considered on -their merits. - -.. note:: - - pip has a helper function for making deprecation easier for pip maintainers. - The supporting documentation can be found in the source code of - ``pip._internal.utils.deprecation.deprecated``. The function is not a part of - pip's public API. - -Release Process -=============== - -#. On the current pip ``master`` branch, generate a new ``AUTHORS.txt`` by - running ``invoke generate.authors`` and commit the results. -#. On the current pip ``master`` branch, make a new commit which bumps the - version in ``pip/__init__.py`` to the release version and adjust the - ``CHANGES.txt`` file to reflect the current date. The release version should - follow a YY.N scheme, where YY is the two digit year, and N is the Nth - release within that year. -#. On the current pip ``master`` branch, generate a new ``NEWS.rst`` by running - ``invoke generate.news`` and commit the results. -#. Create a signed tag of the ``master`` branch of the form ``X.Y.Z`` using the - command ``git tag -s X.Y.Z``. -#. Checkout the tag using ``git checkout X.Y.Z`` and create the distribution - files using ``python setup.py sdist bdist_wheel``. -#. Upload the distribution files to PyPI using twine - (``twine upload -s dist/*``). The upload should include GPG signatures of - the distribution files. -#. Push all of the changes. -#. Regenerate the ``get-pip.py`` script by running - ``invoke generate.installer`` in the get-pip repository, and committing the - results. - - -Creating a Bugfix Release -========================= - -Sometimes we need to release a bugfix release of the form ``X.Y.Z+1``. In order -to create one of these the changes should already be merged into the -``master`` branch. - -#. Create a new ``release/YY.N.Z+1`` branch off of the ``YY.N`` tag using the - command ``git checkout -b release/YY.N.Z+1 YY.N``. -#. Cherry pick the fixed commits off of the ``master`` branch, fixing any - conflicts and moving any changelog entries from the development version's - changelog section to the ``YY.N.Z+1`` section. -#. Push the ``release/YY.N.Z+1`` branch to github and submit a PR for it against - the ``master`` branch and wait for the tests to run. -#. Once tests run, merge the ``release/YY.N.Z+1`` branch into master, and follow - the above release process starting with step 4. - - -.. _`mailing list`: https://mail.python.org/mailman/listinfo/distutils-sig -.. _`towncrier`: https://pypi.org/project/towncrier/ -.. _`Travis CI`: https://travis-ci.org/ -.. _`Appveyor CI`: https://www.appveyor.com/ -.. _`.travis.yml`: https://github.com/pypa/pip/blob/master/.travis.yml -.. _`appveyor.yml`: https://github.com/pypa/pip/blob/master/appveyor.yml -.. _`Travis CI Pull Requests`: https://travis-ci.org/pypa/pip/pull_requests -.. _`tools/tests-requirements.txt`: https://github.com/pypa/pip/blob/master/tools/tests-requirements.txt diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst new file mode 100644 index 00000000000..8213237550d --- /dev/null +++ b/docs/development/contributing.rst @@ -0,0 +1,238 @@ +=================== +Contributing to pip +=================== + +.. todo + Create a "guide" to pip's internals and link to it from here saying + "you might want to take a look at the guide" + + +Submitting Pull Requests +======================== + +Submit pull requests against the ``master`` branch, providing a good +description of what you're doing and why. You must have legal permission to +distribute any code you contribute to pip and it must be available under the +MIT License. + +Provide tests that cover your changes and run the tests locally first. pip +:ref:`supports ` multiple Python versions and +operating systems. Any pull request must consider and work on all these +platforms. + +Pull Requests should be small to facilitate easier review. Keep them +self-contained, and limited in scope. `Studies have shown`_ that review quality +falls off as patch size grows. Sometimes this will result in many small PRs to +land a single large feature. In particular, pull requests must not be treated +as "feature branches", with ongoing development work happening within the PR. +Instead, the feature should be broken up into smaller, independent parts which +can be reviewed and merged individually. + +Additionally, avoid including "cosmetic" changes to code that +is unrelated to your change, as these make reviewing the PR more difficult. +Examples include re-flowing text in comments or documentation, or addition or +removal of blank lines or whitespace within lines. Such changes can be made +separately, as a "formatting cleanup" PR, if needed. + +Automated Testing +================= + +All pull requests and merges to 'master' branch are tested using `Travis CI`_ +and `Appveyor CI`_ based on our `.travis.yml`_ and `appveyor.yml`_ files. + +You can find the status and results to the CI runs for your PR on GitHub's Web +UI for the pull request. You can also find links to the CI services' pages for +the specific builds in the form of "Details" links, in case the CI run fails +and you wish to view the output. + +To trigger CI to run again for a pull request, you can close and open the pull +request or submit another change to the pull request. If needed, project +maintainers can manually trigger a restart of a job/build. + + +NEWS Entries +============ + +The ``NEWS.rst`` file is managed using `towncrier`_ and all non trivial changes +must be accompanied by a news entry. + +To add an entry to the news file, first you need to have created an issue +describing the change you want to make. A Pull Request itself *may* function as +such, but it is preferred to have a dedicated issue (for example, in case the +PR ends up rejected due to code quality reasons). + +Once you have an issue or pull request, you take the number and you create a +file inside of the ``news/`` directory named after that issue number with an +extension of ``removal``, ``feature``, ``bugfix``, or ``doc``. Thus if your +issue or PR number is ``1234`` and this change is fixing a bug, then you would +create a file ``news/1234.bugfix``. PRs can span multiple categories by creating +multiple files (for instance, if you added a feature and deprecated/removed the +old feature at the same time, you would create ``news/NNNN.feature`` and +``news/NNNN.removal``). Likewise if a PR touches multiple issues/PRs you may +create a file for each of them with the exact same contents and Towncrier will +deduplicate them. + +Contents of a NEWS entry +------------------------ + +The contents of this file are reStructuredText formatted text that will be used +as the content of the news file entry. You do not need to reference the issue +or PR numbers here as towncrier will automatically add a reference to all of +the affected issues when rendering the news file. + +In order to maintain a consistent style in the ``NEWS.rst`` file, it is +preferred to keep the news entry to the point, in sentence case, shorter than +80 characters and in an imperative tone -- an entry should complete the sentence +"This change will ...". In rare cases, where one line is not enough, use a +summary line in an imperative tone followed by a blank line separating it +from a description of the feature/change in one or more paragraphs, each wrapped +at 80 characters. Remember that a news entry is meant for end users and should +only contain details relevant to an end user. + +Choosing the type of NEWS entry +------------------------------- + +A trivial change is anything that does not warrant an entry in the news file. +Some examples are: Code refactors that don't change anything as far as the +public is concerned, typo fixes, white space modification, etc. To mark a PR +as trivial a contributor simply needs to add a randomly named, empty file to +the ``news/`` directory with the extension of ``.trivial``. If you are on a +POSIX like operating system, one can be added by running +``touch news/$(uuidgen).trivial``. On Windows, the same result can be achieved +in Powershell using ``New-Item "news/$([guid]::NewGuid()).trivial"``. Core +committers may also add a "trivial" label to the PR which will accomplish the +same thing. + +Upgrading, removing, or adding a new vendored library gets a special mention +using a ``news/.vendor`` file. This is in addition to any features, +bugfixes, or other kinds of news that pulling in this library may have. This +uses the library name as the key so that updating the same library twice doesn't +produce two news file entries. + +Changes to the processes, policies, or other non code related changed that are +otherwise notable can be done using a ``news/.process`` file. This is not +typically used, but can be used for things like changing version schemes, +updating deprecation policy, etc. + + +Updating your branch +==================== + +As you work, you might need to update your local master branch up-to-date with +the ``master`` branch in the main pip repository, which moves forward as the +maintainers merge pull requests. Most people working on the project use the +following workflow. + +This assumes that you have Git configured so that when you run the following +command: + +.. code-block:: console + + git remote -v + +Your output looks like this: + +.. code-block:: console + + origin https://github.com/USERNAME/pip.git (fetch) + origin https://github.com/USERNAME/pip.git (push) + upstream https://github.com/pypa/pip.git (fetch) + upstream https://github.com/pypa/pip.git (push) + +In the example above, ``USERNAME`` is your username on GitHub. + +First, fetch the latest changes from the main pip repository, ``upstream``: + +.. code-block:: console + + git fetch upstream + +Then, check out your local ``master`` branch, and rebase the changes on top of +it: + +.. code-block:: console + + git checkout master + git rebase upstream/master + +At this point, you might have to `resolve merge conflicts`_. Once this is done, +push the updates you have just made to your local ``master`` branch to your +``origin`` repository on GitHub: + +.. code-block:: console + + git checkout master + git push origin master + +Now your local ``master`` branch and the ``master`` branch in your ``origin`` +repo have been updated with the most recent changes from the main pip +repository. + +To keep your branches updated, the process is similar: + +.. code-block:: console + + git checkout awesome-feature + git fetch upstream + git rebase upstream/master + +Now your branch has been updated with the latest changes from the +``master`` branch on the upstream pip repository. + +It's good practice to back up your branches by pushing them to your +``origin`` on GitHub as you are working on them. To push a branch, +run this command: + +.. code-block:: console + + git push origin awesome-feature + +In this example, ```` is the name of your branch. This +will push the branch you are working on to GitHub, but will not +create a PR. + +Once you have pushed your branch to your ``origin``, if you need to +update it again, you will have to force push your changes by running the +following command: + +.. code-block:: console + + git push -f origin awesome-feature + +The ``-f`` (or ``--force``) flag after ``push`` forces updates from your local +branch to update your ``origin`` branch. If you have a PR open on your +branch, force pushing will update your PR. (This is a useful command +when someone requests changes on a PR.) + +If you get an error message like this: + +.. code-block:: console + + ! [rejected] awesome-feature -> awesome-feature (non-fast-forward) + error: failed to push some refs to 'https://github.com/USERNAME/pip.git' + hint: Updates were rejected because the tip of your current branch is behind + hint: its remote counterpart. Integrate the remote changes (e.g. + hint: 'git pull ...') before pushing again. + hint: See the 'Note about fast-forwards' in 'git push --help' for details. + +Try force-pushing your branch with ``push -f``. + +The ``master`` branch in the main pip repository gets updated frequently, so +you might have to update your branch at least once while you are working on it. + + +Becoming a maintainer +===================== + +If you want to become an official maintainer, start by helping out. + +Later, when you think you're ready, get in touch with one of the maintainers +and they will initiate a vote. + +.. _`Studies have shown`: https://smartbear.com/smartbear/media/pdfs/wp-cc-11-best-practices-of-peer-code-review.pdf +.. _`resolve merge conflicts`: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ +.. _`Travis CI`: https://travis-ci.org/ +.. _`Appveyor CI`: https://www.appveyor.com/ +.. _`.travis.yml`: https://github.com/pypa/pip/blob/master/.travis.yml +.. _`appveyor.yml`: https://github.com/pypa/pip/blob/master/appveyor.yml +.. _`towncrier`: https://pypi.org/project/towncrier/ diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst new file mode 100644 index 00000000000..6a91b605d27 --- /dev/null +++ b/docs/development/getting-started.rst @@ -0,0 +1,110 @@ +=============== +Getting Started +=============== + +We’re pleased that you are interested in working on pip. + +This document is meant to get you setup to work on pip and to act as a guide and +reference to the the development setup. If you face any issues during this +process, please `open an issue`_ about it on the issue tracker. + +Development tools +================= + +pip uses :pypi:`tox` for testing against multiple different Python environments +and ensuring reproducible environments for linting and building documentation. + +For developing pip, you need to install ``tox`` on your system. Often, you can +just do ``python -m pip install tox`` to install and use it. + +Running Tests +------------- + +pip uses the :pypi:`pytest` test framework, :pypi:`mock` and :pypi:`pretend` +for testing. These are automatically installed by tox for running the tests. + +To run tests locally, run: + +.. code-block:: console + + $ tox -e py36 + +The example above runs tests against Python 3.6. You can also use other +versions like ``py27`` and ``pypy3``. + +``tox`` has been configured to any additional arguments it is given to +``pytest``. This enables the use of pytest's `rich CLI`_. As an example, you +can select tests using the various ways that pytest provides: + +.. code-block:: console + + $ # Using file name + $ tox -e py36 -- tests/functional/test_install.py + $ # Using markers + $ tox -e py36 -- -m unit + $ # Using keywords + $ tox -e py36 -- -k "install and not wheel" + +Running pip's test suite requires supported version control tools (subversion, +bazaar, git, and mercurial) to be installed. If you are missing one of the VCS +tools, you can tell pip to skip those tests: + +.. code-block:: console + + $ tox -e py36 -- -k "not svn" + $ tox -e py36 -- -k "not (svn or git)" + +Running Linters +--------------- + +pip uses :pypi:`flake8` and :pypi:`isort` for linting the codebase. These +ensure that the codebase is in compliance with :pep:`8` and the imports are +consistently ordered and styled. + +To use linters locally, run: + +.. code-block:: console + + $ tox -e lint-py2 + $ tox -e lint-py3 + +The above commands run the linters on Python 2 followed by Python 3. + +.. note:: + + Do not silence errors from flake8 with ``# noqa`` comments or otherwise. + The only exception to this is silencing unused-import errors for imports + related to static type checking as currently `flake8 does not understand + PEP 484 type-comments`_. + +Running mypy +------------ + +pip uses :pypi:`mypy` to run static type analysis, which helps catch certain +kinds of bugs. The codebase uses `PEP 484 type-comments`_ due to compatibility +requirements with Python 2.7. + +To run the ``mypy`` type checker, run: + +.. code-block:: console + + $ tox -e mypy + +Building Documentation +---------------------- + +pip's documentation is built using :pypi:`Sphinx`. The documentation is written +in reStructuredText. + +To build it locally, run: + +.. code-block:: console + + $ tox -e docs + +The built documentation can be found in the ``docs/build`` folder. + +.. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Trouble+with+pip+development+environment +.. _`flake8 does not understand PEP 484 type-comments`: https://gitlab.com/pycqa/flake8/issues/118 +.. _`PEP 484 type-comments`: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code +.. _`rich CLI`: https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 00000000000..4124d831f56 --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,25 @@ +Development +=========== + +pip is a volunteer maintained open source project and we welcome contributions +of all forms. The sections below will help you get started with development, +testing, and documentation. + +You can also join ``#pypa`` (general packaging discussion and user support) and +``#pypa-dev`` (discussion about development of packaging tools) `on Freenode`_, +or the `pypa-dev mailing list`_, to ask questions or get involved. + +.. toctree:: + :maxdepth: 2 + + getting-started + contributing + release-process + +.. note:: + + pip's development documentation has been rearranged and some older + references might be broken. + +.. _`on Freenode`: https://webchat.freenode.net/?channels=%23pypa-dev,pypa +.. _`pypa-dev mailing list`: https://groups.google.com/forum/#!forum/pypa-dev diff --git a/docs/development/release-process.rst b/docs/development/release-process.rst new file mode 100644 index 00000000000..c90c08f7141 --- /dev/null +++ b/docs/development/release-process.rst @@ -0,0 +1,103 @@ +===================== +pip's release process +===================== + + +Release Cadence +=============== + +The pip project has a release cadence of releasing whatever is on ``master`` +every 3 months. This gives users a predictable pattern for when releases +are going to happen and prevents locking up improvements for fixes for long +periods of time, while still preventing massively fracturing the user base +with version numbers. + +Our release months are January, April, July, October. The release date within +that month will be up to the release manager for that release. If there are +no changes, then that release month is skipped and the next release will be +3 month later. + +The release manager may, at their discretion, choose whether or not there +will be a pre-release period for a release, and if there is may extend that +period into the next month if needed. + +Because releases are made direct from the ``master`` branch, it is essential +that ``master`` is always in a releasable state. It is acceptable to merge +PRs that partially implement a new feature, but only if the partially +implemented version is usable in that state (for example, with reduced +functionality or disabled by default). In the case where a merged PR is found +to need extra work before being released, the release manager always has the +option to back out the partial change prior to a release. The PR can then be +reworked and resubmitted for the next release. + + +Deprecation Policy +================== + +Any change to pip that removes or significantly alters user-visible behavior +that is described in the pip documentation will be deprecated for a minimum of +6 months before the change occurs. Deprecation will take the form of a warning +being issued by pip when the feature is used. Longer deprecation periods, or +deprecation warnings for behavior changes that would not normally be covered by +this policy, are also possible depending on circumstances, but this is at the +discretion of the pip developers. + +Note that the documentation is the sole reference for what counts as agreed +behavior. If something isn't explicitly mentioned in the documentation, it can +be changed without warning, or any deprecation period, in a pip release. +However, we are aware that the documentation isn't always complete - PRs that +document existing behavior with the intention of covering that behavior with +the above deprecation process are always acceptable, and will be considered on +their merits. + +.. note:: + + pip has a helper function for making deprecation easier for pip maintainers. + The supporting documentation can be found in the source code of + ``pip._internal.utils.deprecation.deprecated``. The function is not a part of + pip's public API. + + +Release Process +=============== + +Creating a new release +---------------------- + +#. On the current pip ``master`` branch, generate a new ``AUTHORS.txt`` by + running ``invoke generate.authors`` and commit the results. +#. On the current pip ``master`` branch, make a new commit which bumps the + version in ``pip/__init__.py`` to the release version and adjust the + ``CHANGES.txt`` file to reflect the current date. The release version should + follow a YY.N scheme, where YY is the two digit year, and N is the Nth + release within that year. +#. On the current pip ``master`` branch, generate a new ``NEWS.rst`` by running + ``invoke generate.news`` and commit the results. +#. Create a signed tag of the ``master`` branch of the form ``YY.N`` using the + command ``git tag -s YY.N``. +#. Checkout the tag using ``git checkout YY.N`` and create the distribution + files using ``python setup.py sdist bdist_wheel``. +#. Upload the distribution files to PyPI using twine + (``twine upload -s dist/*``). The upload should include GPG signatures of + the distribution files. +#. Push all of the changes. +#. Regenerate the ``get-pip.py`` script by running + ``invoke generate.installer`` in the get-pip repository, and committing the + results. + +Creating a bug-fix release +-------------------------- + +Sometimes we need to release a bugfix release of the form ``YY.N.Z+1``. In +order to create one of these the changes should already be merged into the +``master`` branch. + +#. Create a new ``release/YY.N.Z+1`` branch off of the ``YY.N`` tag using the + command ``git checkout -b release/YY.N.Z+1 YY.N``. +#. Cherry pick the fixed commits off of the ``master`` branch, fixing any + conflicts and moving any changelog entries from the development version's + changelog section to the ``YY.N.Z+1`` section. +#. Push the ``release/YY.N.Z+1`` branch to github and submit a PR for it against + the ``master`` branch and wait for the tests to run. +#. Once tests run, merge the ``release/YY.N.Z+1`` branch into master, and follow + the above release process starting with step 4. diff --git a/docs/index.rst b/docs/index.rst index caf0725a65e..64bbb79f3ee 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,5 +18,5 @@ for installing Python packages. installing user_guide reference/index - development + development/index news diff --git a/docs/installing.rst b/docs/installing.rst index ac9cd4fb241..795feedbf50 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -6,10 +6,10 @@ Installation Do I need to install pip? ------------------------- -pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4 -downloaded from `python.org `_ or if you are working -in a :ref:`Virtual Environment ` -created by :ref:`pypug:virtualenv` or :ref:`pyvenv `. +pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4 +downloaded from `python.org `_ or if you are working +in a :ref:`Virtual Environment ` +created by :ref:`pypug:virtualenv` or :ref:`pyvenv `. Just make sure to :ref:`upgrade pip `. @@ -36,7 +36,7 @@ Then run the following:: system or another package manager. ``get-pip.py`` does not coordinate with those tools, and may leave your system in an inconsistent state. -``get-pip.py`` also installs :ref:`pypug:setuptools` [2]_ and :ref:`pypug:wheel` +``get-pip.py`` also installs :ref:`pypug:setuptools` [2]_ and :ref:`pypug:wheel` if they are not already. :ref:`pypug:setuptools` is required to install :term:`source distributions `. Both are required in order to build a :ref:`Wheel cache` (which improves installation @@ -106,6 +106,8 @@ On Windows [4]_:: python -m pip install -U pip +.. _compatibility-requirements: + Python and OS Compatibility ---------------------------