Contributing FAQ

Django Guardian is an open-source project, and we welcome contributions from the community. However, since Guardian is a security-focused project, there are additional guidelines and rules for contributors that may be a little different from other open-source projects.

Why is `next` the default branch?

The main branch is always in a production-ready state. The tip of main contains the latest full (ie non-candidate) release. New PRs should be made into the next branch to be first release as a candidate and batched with other PRs into the next versioned release.

The next branch, can potentially break. As a user, you should NEVER use non-main branches in production (if you're desperate for a feature or fix not yet released, either use a SHA to install at a specific commit, or install a release candidate tag).

How do I file a ticket?

Have a bug, feature request, or question?

Create a ticket in The repo issue tracker

If you would like to contribute, it's important to make sure that your ideas are in line with the project goals before you start working. Describe your bug, feature request, or question with enough details and context to allow the team to understand your request.

How do I get involved?

You are cordially invited to contribute to the Django Guardian project! Django Guardian welcomes all types of contributions, from bug reports to documentation.

Start by filing a ticket in the issue tracker.

Then, fork the project on github, create a separate branch, work on it, push changes to your fork and create a pull request.

Here is a quick how to:

Fork a project here

Checkout project to your local machine

$ git clone git@github.com:YOUR_NAME/django-guardian.git

Create a new branch with name describing change you are going to work on
```
$ git checkout -b support-for-custom-model
```
Perform changes at newly created branch. Remember to include tests (if this is code related change) and run test suite. See running tests documentation <testing>. Also, remember to add yourself to the bottom of the authors entry in pyproject.toml.
(Optional) Squash commits. If you have multiple commits and it doesn't make much sense to have them separated (and it usually makes little sense), please consider merging all changes into single commit (if you're not sure about this, the maintainers will likely squash commits on merging, so don't worry too much).
Make sure your PR is up to date with latest changes (it should be ahead of the "tip" of the next branch that you're mergin into). Please see GitHub's help on interactive rebasing if you need help with that.
Publish changes
```
$ git push origin YOUR_BRANCH_NAME
```
Create a Pull Request. Usually it's as simple as opening up https://github.com/YOUR_NAME/django-guardian and clicking on review button for newly created branch. There you can make final review of your changes and if everything seems fine, create a Pull Request.

Installing dev dependencies and running tests

Install the uv package manager by following the instructions here.

Install tox tool and its plugins into your local environment:

uv tool install --python-preference only-managed --python 3.13 tox --with . --with tox-uv

First check all the test environments will install for you (without actually running the tests):
```
tox run -n
```
Run all the tests:
```
tox run
```

Under the hood, the tests use pytest so of course, you can set up your IDE to use pytest directly alternatively.

Why was my issue/pull request closed?

We usually put an explanation when we close an issue or PR. Common reasons:

no reply for over a month after our last comment or review
no tests for the changes, or failing tests
there are performance implications of the changes
PRs made out of the blue without filing an issue first
breaking changes we don't want to introduce
out-of-scope features
features or approaches that are difficult to support going forwards

How do I update the documentation?

Documentation is stored in docs folder. To update the documentation, you can edit the Markdown files directly. If you need to add new pages, or view the documentation locally, you can use the following steps:

Install the required packages:

pip install -r docs/requirements.txt

Run the documentation server:

mkdocs serve

The CLI will provide you a link to view the documentation running locally (usually http://127.0.0.1:8000).

See the ReadTheDocs' documentation on using MkDocs for more information.

How do I make a release?

See the dedicated Release Process page for full instructions on creating standard releases, release candidates, and hotfix releases.