Submitting patches#
Before you submit a patch, you may want to look at our guide to the Warehouse codebase.
As you work on your patch, keep this in mind:
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, follow the directions on the security page.
Code#
When in doubt, refer to the Black Code Style for Python code formatting. You
can reformat your code according to this code style by running make reformat
against it. You can check if your code meets all 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.
Translations#
When making changes to files with strings marked for translation, it’s
necessary to update references to these files any time source strings are change, or the
line numbers of the source strings in the source files. This can be done by running make translations
.
For instructions on how to mark strings and views for translation, see the Translations docs.
Keeping your local branch updated#
As you work, you will need to keep your local main
branch up-to-date with
the main
branch in the main Warehouse 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:
git remote -v
Your output looks like this:
origin https://github.com/username/warehouse.git (fetch)
origin https://github.com/username/warehouse.git (push)
upstream https://github.com/pypi/warehouse.git (fetch)
upstream https://github.com/pypi/warehouse.git (push)
In the example above, <username>
is your username on GitHub.
First, fetch the latest changes from the main Warehouse repository,
upstream
:
git fetch upstream
Then, check out your local main
branch, and rebase the changes on top of
it:
git checkout main
git rebase upstream/main
Next, push the updates you have just made to your local main
branch to
your origin
repository on GitHub:
git checkout main
git push origin main
Now your local main
branch and the main
branch in your origin
repo have been updated with the most recent changes from the main Warehouse
repository.
To keep your feature branches updated, the process is similar:
git checkout awesome-feature
git fetch upstream
git rebase upstream/main
Now your feature branch has been updated with the latest changes from the
main
branch on the upstream Warehouse repository.
It’s good practice to back up your feature branches by pushing them to your
origin
on GitHub as you are working on them. To push a feature branch,
run this command:
git push origin awesome-feature
In this example, <awesome-feature>
is the name of your feature branch. This
will push the feature branch you are working on to GitHub, but will not
create a PR.
Once you have pushed your feature branch to your origin
, if you need to
update it again, you will have to force push your changes by running the
following command:
git push -f origin awesome-feature
The -f
(or --force
) flag after push
forces updates from your local
branch to update your origin
feature branch. If you have a PR open on your
feature 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:
! [rejected] awesome-feature -> awesome-feature (non-fast-forward)
error: failed to push some refs to 'https://github.com/USERNAME/warehouse.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 feature branch with push -f
.
The main
branch in the main Warehouse repository gets updated frequently
as dependency upgrades are merged, so you will probably have to update your
feature branch at least once while you are working on it.