Rework the development documentation #5526

pradyunsg · 2018-06-23T11:21:46Z

The idea here is to make the development processes a bit more approachable to potential contributors by clearly documenting how to work on the project and grouping other information into separate pages.

This PR does so by break up the existing development documentation into 4 parts, with the following structure/changes:

🆕 An inviting introduction that links to various support channels.
- idea + links taken from warehouse's docs
Getting Started
- 🆕 nice link to create issues with specific title in the tracker
  - makes it easy to ask for help
  - Idea from Create new, simpler packaging tutorial packaging.python.org#498
- 🆕 what's needed to work on pip
- how to run various supporting tooling
  - 🆕 how to run linters, mypy, and building docs
  - 🆕 Link to PyPI pages of various projects used (improves discoverablity)
  - Fixes Can't run tests with py.test #4878 by only documenting the tox way of running tests.
Release processes
- Release Cadence, Deprecation Policy and how to do releases
Contributing
- What's expected from a PR
  - reworded to not talk about how to make a PR
- NEWS entries
  - 🆕 Broken up into 3 sections: why, how and "which extension".
- 🆕 How to update (i.e. rebase) a branch/PR
  - derived from warehouse's docs

@brainwane If you could take a look at this and provide some feedback, that'd be awesome. :)

@dstufft The bots would need to be updated for this. This is basically blocked until we figure out a suitable way to change them to link to the new location. IIUC, the URLs would change due to this PR and break any existing links.

As per my understanding, we'd need to update these links:

BrownTruck: can link to "Updating your branch"
pypa-bot: NEWS fragment information
PR template: NEWS fragment information (this is basically in the repo, so it's cool)

I would love to feedback on this from existing contributors and obviously @pypa/pip-committers.

docs/development/getting-started.rst

pradyunsg · 2018-06-23T11:23:52Z

docs/development/getting-started.rst

+
+The built documentation can be found in the ``docs/build`` folder.
+
+.. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Truouble+with+pip+development+environment


Whee. Typo!

pradyunsg · 2018-06-23T11:24:49Z

docs/development/index.rst

+sections below will help you get started with development, testing, and
+documentation.
+
+Please contribute issues, submit bug reports, file feature requests, and help


This section, as a whole, could possibly be worded better.

One thing I think we should mention here is that we support Python 2.7 and 3, and we support Windows and Unix. Contributions must consider all of those cases. While a contribution from someone who only works on Python 2.7 and Unix is appreciated, it's not going to progress unless someone puts in the work to consider Python 3 and Windows, and I think we need to set contributors' expectations here. More generally, contributions need to go beyond "works for me". As a team, we don't have the manpower to take incomplete contributions and complete them ourselves (although we will happily help the contributor to do so with advice and suggestions).

That is probably something that should be clarified in the contributing page, in the "Submitting Pull Requests" section.

On the point of setting contributors' expectations early, totally agree. I think this should mention that pip is a volunteer maintained project.

We could also link from the PR template to the "Submitting Pull Requests" section (while also talking about NEWS fragments).

Coming back around to this, I don't even think this paragraph is even needed here. We don't need to list various ways to interact with the project on GitHub in the "development" documentation.

pradyunsg · 2018-06-23T11:25:29Z

docs/development/getting-started.rst

+-------------
+
+pip uses the :pypi:`pytest` test framework, :pypi:`mock` and :pypi:`pretend`
+for testing. These are automatically installed by tox for running the tests.


Should we also say "and various pytest plugins" here?

IMO no, we don't need to complicate things by adding that much detail.

pradyunsg · 2018-06-23T11:52:06Z

@pypa/pip-committers I'm on the fence as to whether this should get an entry in the NEWS file. On the one hand, it doesn't concern most users. On the other hand, we have a dedicated processes section where this could go and get some visibility.

pfmoore · 2018-06-23T12:01:04Z

docs/development/getting-started.rst

+-------------
+
+pip uses the :pypi:`pytest` test framework, :pypi:`mock` and :pypi:`pretend`
+for testing. These are automatically installed by tox for running the tests.


IMO no, we don't need to complicate things by adding that much detail.

docs/development/getting-started.rst

pfmoore · 2018-06-23T12:24:36Z

docs/development/index.rst

+sections below will help you get started with development, testing, and
+documentation.
+
+Please contribute issues, submit bug reports, file feature requests, and help


One thing I think we should mention here is that we support Python 2.7 and 3, and we support Windows and Unix. Contributions must consider all of those cases. While a contribution from someone who only works on Python 2.7 and Unix is appreciated, it's not going to progress unless someone puts in the work to consider Python 3 and Windows, and I think we need to set contributors' expectations here. More generally, contributions need to go beyond "works for me". As a team, we don't have the manpower to take incomplete contributions and complete them ourselves (although we will happily help the contributor to do so with advice and suggestions).

docs/development/release-process.rst

pradyunsg · 2018-06-23T17:13:23Z

(removed the label so it's harder to accidentally merge)

- Link to compatibility requirements and require compliance - Move licensing details to come earlier - Reword text on cosmetic changes

pradyunsg · 2018-07-15T10:49:24Z

I'm sorry, I don't have time to look at this.

No issues. Thanks for pinging others who might be able to provide feedback here.

Any and all feedback is welcome. :)

BrownTruck · 2018-07-20T17:30:05Z

Hello!

I am an automated bot and I have noticed that this pull request is not currently able to be merged. If you are able to either merge the master branch into this pull request or rebase this pull request against master then it will eligible for code review and hopefully merging!

theacodes · 2018-07-23T18:00:03Z

This looks great! I'd say go ahead and merge this and iterate if needed.

pradyunsg · 2018-07-23T18:10:40Z

Thanks for taking a look @theacodes! ^>^

I was thinking about removing the "blocking" that the linking to "Writing a NEWS entry" involves here. I guess just adding a temporary? section/note saying that has been moved to a different location should suffice for now. :)

pradyunsg · 2018-07-23T19:38:16Z

I'll go ahead and merge this since this is a (big!) improvement over status quo and as @theacodes suggests, we can iterate on it. :)

pradyunsg added type: docs Documentation related state: blocked Can not be done until something else is done type: maintenance Related to Development and Maintenance Processes labels Jun 23, 2018

pradyunsg added this to the Internal Cleansing milestone Jun 23, 2018

pradyunsg self-assigned this Jun 23, 2018

pradyunsg requested review from dstufft, brainwane and a team June 23, 2018 11:21

pradyunsg commented Jun 23, 2018

View reviewed changes

pradyunsg mentioned this pull request Jun 23, 2018

Can't run tests with py.test #4878

Closed

pradyunsg added the skip news Does not need a NEWS file entry (eg: trivial changes) label Jun 23, 2018

pfmoore reviewed Jun 23, 2018

View reviewed changes

This was referenced Jun 23, 2018

When basepython is pythonX and is missing, try to use various pythonX.Y tox-dev/tox#854

Closed

Fallback to py executable on Windows tox-dev/tox#855

Closed

pradyunsg removed the skip news Does not need a NEWS file entry (eg: trivial changes) label Jun 23, 2018

pradyunsg added 13 commits July 2, 2018 19:02

Start breaking development documentation

30dcc7d

Move release-process docs to separate page

bf0d736

Move and expand contribution related notes

8891656

Add a new section documenting development processes

c1780e0

Document how to submit pull requests

b6cdf5d

Document how to rebase a branch

8344642

Add shorthand for pypi projects

ff1cdc7

Use newer development docs

2e9e42b

Polish the Release Process documentation

868dd68

Don't mention various ways to contribute

0db7d17

Mention that pip is volunteer maintained

2b57b8d

Provide examples of running specific tests using tox

60ef05b

Improve "Submitting Pull Requests" section

98ddd2d

- Link to compatibility requirements and require compliance - Move licensing details to come earlier - Reword text on cosmetic changes

pradyunsg removed the request for review from brainwane July 15, 2018 10:48

pradyunsg added 2 commits July 17, 2018 13:59

Merge branch 'master' into docs/improve-dev-docs

1933dac

Add the deprecation policy changes from fde9eb6

3c073f9

pypa-bot removed the needs rebase or merge PR has conflicts with current master label Jul 17, 2018

pradyunsg mentioned this pull request Jul 17, 2018

Fix grammatical and structural errors in development.rst #5610

Closed

xavfernandez approved these changes Jul 17, 2018

View reviewed changes

BrownTruck added the needs rebase or merge PR has conflicts with current master label Jul 20, 2018

pradyunsg added 2 commits July 22, 2018 18:32

Merge branch 'master' into docs/improve-dev-docs

5fceb47

Add the deprecation helper information from b6dae7a

47e8703

pypa-bot removed the needs rebase or merge PR has conflicts with current master label Jul 22, 2018

pradyunsg mentioned this pull request Jul 22, 2018

Updating Release Process documentation based on 18.0 release experience #5633

Closed

theacodes approved these changes Jul 23, 2018

View reviewed changes

pradyunsg added 2 commits July 23, 2018 23:55

Merge branch 'master' into docs/improve-dev-docs

971456b

Add a note saying older references might be broken

468e38f

pradyunsg added skip news Does not need a NEWS file entry (eg: trivial changes) and removed state: blocked Can not be done until something else is done labels Jul 23, 2018

Update the link in the pull request template

0d74b20

pradyunsg merged commit 1e09062 into pypa:master Jul 23, 2018

pradyunsg deleted the docs/improve-dev-docs branch July 23, 2018 19:38

pradyunsg added the pradyunsg-moving-issues label May 25, 2019

pradyunsg removed pradyunsg-moving-issues labels May 25, 2019

lock bot added the auto-locked Outdated issues that have been locked by automation label Jun 24, 2019

lock bot locked as resolved and limited conversation to collaborators Jun 24, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework the development documentation #5526

Rework the development documentation #5526

pradyunsg commented Jun 23, 2018 •

edited

Loading

pradyunsg Jun 23, 2018

pradyunsg Jun 23, 2018

pfmoore Jun 23, 2018

pradyunsg Jun 23, 2018 •

edited

Loading

pradyunsg Jun 23, 2018

pradyunsg Jul 2, 2018

pradyunsg Jun 23, 2018

pfmoore Jun 23, 2018

pradyunsg commented Jun 23, 2018

pfmoore Jun 23, 2018

pfmoore Jun 23, 2018

pradyunsg commented Jun 23, 2018

pradyunsg commented Jul 15, 2018

BrownTruck commented Jul 20, 2018

theacodes commented Jul 23, 2018

pradyunsg commented Jul 23, 2018

pradyunsg commented Jul 23, 2018


		The built documentation can be found in the ``docs/build`` folder.

		.. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Truouble+with+pip+development+environment

Rework the development documentation #5526

Rework the development documentation #5526

Conversation

pradyunsg commented Jun 23, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pradyunsg Jun 23, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pradyunsg commented Jun 23, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pradyunsg commented Jun 23, 2018

pradyunsg commented Jul 15, 2018

BrownTruck commented Jul 20, 2018

theacodes commented Jul 23, 2018

pradyunsg commented Jul 23, 2018

pradyunsg commented Jul 23, 2018

pradyunsg commented Jun 23, 2018 •

edited

Loading

pradyunsg Jun 23, 2018 •

edited

Loading