Contributing

Thank you for considering contributing to django-allauth! This document outlines the process for contributing to the project and sets up your development environment.

Code of Conduct

In the interest of fostering an open and welcoming community, we as contributors and maintainers pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Getting Started

Setting Up Your Development Environment

There are two primary ways to set up your development environment:

Option 1: Standard Python Virtual Environment (Recommended for Beginners)

Install system dependencies

Before creating a virtual environment, you’ll need to install some system dependencies:

On macOS:

# Using Homebrew
brew install libxml2 libxmlsec1 pkg-config openssl

On Ubuntu/Debian:

sudo apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl pkg-config

On RHEL/CentOS/Fedora:

sudo dnf install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel

Create and activate a virtual environment

# Create a virtual environment
python -m venv virtualenv

# Activate it
# On Windows:
virtualenv\Scripts\activate
# On macOS/Linux:
source virtualenv/bin/activate

Install django-allauth in development mode

# Install development dependencies
pip install -r requirements-dev.txt

Option 2: Using devenv/Nix (Recommended for Advanced Users)

If you prefer a more isolated and reproducible development environment, you can use Nix-based devenv:

Install devenv (If you don’t have it already)

Follow the official installation instructions.
Activate the developer environment
```
# This will create an isolated environment with all required dependencies
devenv shell
```
Note: The first time you run this command, it may take a significant amount of time as it builds all dependencies. Subsequent launches will be much faster.

Running Tests

django-allauth uses a comprehensive test suite. You can run tests in several ways:

Using pytest directly

# Run all tests for the default setup
pytest allauth/

# Run tests with a specific Django settings module
pytest --ds=tests.projects.regular.settings tests/

# Run a specific test file
pytest tests/apps/account/test_login.py

Note, if you are using MacOS, using pip and get this error when run tests:

import xmlsec
ImportError: dlopen( ...  symbol not found in flat namespace '_xmlSecOpenSSLTransformHmacRipemd160GetKlass')

You can try:

pip uninstall xmlsec lxml
pip install --no-binary :all: xmlsec
# Ref: https://github.com/xmlsec/python-xmlsec/issues/320

Using nox (recommended)

Nox automates testing across different Python and Django versions:

# List all available sessions
nox --list

# Run tests for a specific Python version
nox -x --session "test-3.11"

# Run tests for specific environment
nox -x --session "test-3.11" --python 3.11 -- --ds=tests.projects.regular.settings tests/apps/account/test_login.py

Run Code Quality Checks

# Run all linting checks
nox -t lint

# Run specific check
nox --session black
nox --session isort
nox --session flake8
nox --session bandit
nox --session djlint

Building Documentation

Documentation is built using Sphinx:

# Build the documentation
nox --session docs

The built documentation will be available in the docs/_build/html directory.

Development Workflow

Create a new branch for your feature or bugfix

git checkout -b feature/your-feature-name

Make your changes and add tests

All new features should include proper tests.
Run tests locally to ensure everything passes
```
nox -x --session "test-3.11"
```
Run code quality checks
```
nox -t lint
```
Commit your changes with meaningful commit messages
Submit a pull request to the main repository

Pull Request Guidelines

Update documentation for significant changes
Add tests for new functionality
Ensure all tests pass
Follow the project’s code style
Keep pull requests focused on a single topic
Write clear, descriptive commit messages

Additional Resources

Thank you for your contributions!