Submitting patches

  • Always make a new branch for your work.
  • Patches should be small to facilitate easier review. 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.
  • You must have legal permission to distribute any code you contribute to Warehouse, and it must be available under the Apache Software License Version 2.0.

If you believe you’ve identified a security issue in Warehouse, please follow the directions on the security page.

Code

When in doubt, refer to PEP 8 for Python code. You can check if your code meets our automated requirements by running make lint against it.

Write comments as complete sentences.

Class names which contains acronyms or initialisms should always be capitalized. A class should be named HTTPClient, not HttpClient.

Every code file must start with the boilerplate licensing notice:

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

You can view Patterns to see more patterns that should be used within Warehouse.

Tests

All code changes must be accompanied by unit tests with 100% code coverage (as measured by coverage.py).

Documentation

Important information should be documented with prose in the docs section. To ensure it builds and passes doc8 style checks you can run make docs and make lint respectively.