Adding PUP-8

README.md

@@ -15,5 +15,6 @@ Number | Title
 5 | [Common Cure Rights Commitment](https://github.com/pulp/pups/blob/master/pup-0005.md)
 6 | [Commit bit assignment](https://github.com/pulp/pups/blob/master/pup-0006.md)
 7 | [Two-factor authentication](https://github.com/pulp/pups/blob/master/pup-0007.md)
+8 | [Python Code Style and Tools](https://github.com/pulp/pups/blob/master/pup-0008.md)
 
 ### Rejected

pup-0008.md

@@ -0,0 +1,86 @@
+---
+title: Python Code Style and Tools
+author: David Davis
+created: 8-Jun-2019
+status: Approved
+version: 1
+---
+
+## Summary
+
+PUP-8 proposes the adoption of an official Python code style and set of tools for the Pulp
+3 community.
+
+### Background
+
+While most Pulp projects adhere to PEP 8[0], there is still room for different code styles to emerge
+and different toolsets to be used to enforce style for Python code. This PUP seeks to come to a
+common agreement about which style and tools we use. Specifically, this PUP proposes adoption of
+black[1] along with pydocstyle[2] as the official toolset for formatting and linting Python code.
+
+## Motivation
+
+Different coding styles in Pulp 3 are beginning to emerge within the Pulp 3 community that could
+make it difficult to switch from one repo or plugin to another. Moreover, style comments create a
+lot of noise in PRs and can lead to bikeshedding[3]. In order to free developers from having to
+worry about code style, PUP-8 seeks to adopt a single style along with common tooling to aid in
+writing Python code.
+
+Another added benefit is that using an autoformatter can make it easier for newer Pulp users
+(especially those unfamiliar with Python) to create mergeable PRs. The PR process can be a barrier
+to entry for some users and removing style concerns can help to get PRs merged faster.
+
+## Detailed Design
+
+In order to implement this proposal, black and pydocstyle will be used/enforced in the core
+repositories (pulpcore, pulpcore-plugin, etc). This will be done via CI. Locally, it will be up to
+users to choose how they run these tools.
+
+They will also be added to the plugin_template so plugins can leverage them. If approved, this PUP
+can also serve as documentation for what the official style and set of linting tools are for Python
+code in the Pulp community.
+
+## Drawbacks
+
+There are a few drawbacks to using black. The main one is that it is an opinionated style and tool.
+Not everyone is going to agree with all of its style choices. It is worth noting though that other
+popular projects such as django have adopted black[4]. So its style will likely become more
+commonplace in the Python community.
+
+Another concern will be that reformatting all of Pulp's python code will likely touch a lot of
+places within our codebase and create a lot of noise in git history. However, this would be a
+problem with the adoption of any style or autoformatter. Also, adopting black should reduce git
+noise in the long run as without it, developers sometimes change style (e.g. indentation) in
+commits.
+
+A third concern is that the changes introduced by these tools are irreversible in the sense that we
+cannot easily unformat our code to be the way it was before these tools. We can however adopt other
+tools and use those to format our code. So while switching from one lint style to another is
+possible, it will be hard or impossible to revert our code to the state it was before we start using
+black and pydocstyle.
+
+The last drawback is that black is still beta at the time of this PUP. One option would be to wait
+for it to go stable first.
+
+## Alternatives
+
+There are other tools for formatting code: autopep8 and yapf. Autopep8 will only format code to meet
+pep8 standards. As described earlier, it leaves a lot of room for different code styles to emerge.
+
+The other tool, yapf, is maintained by Google. However, yapf is not PEP-8 compliant. It is also
+highly configurable which may or may not be considered as a benefit.
+
+Neither tools are as popular and as the django DEP-8 mentions, "black is maintained in the Python
+GitHub organization, it has a good chance of becoming a standard tool of the Python community."
+
+## Rollout
+
+If this PUP is accepted, we will open issues to add black and pydocstyle to each core repository
+along with an issue to add documentation for plugin writers on which style and set of tools we
+recommend for Python code.
+
+[0] https://www.python.org/dev/peps/pep-0008/
+[1] https://github.com/python/black
+[2] http://www.pydocstyle.org
+[3] https://en.wikipedia.org/wiki/Law_of_triviality
+[4] https://github.com/django/deps/blob/master/accepted/0008-black.rst