# 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)

1. 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

2. 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

3. 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:

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

   Follow the official installation instructions.

2. 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

1. Create a new branch for your feature or bugfix

       git checkout -b feature/your-feature-name

2. Make your changes and add tests

   All new features should include proper tests.

3. Run tests locally to ensure everything passes

       nox -x --session "test-3.11"

4. Run code quality checks

       nox -t lint

5. Commit your changes with meaningful commit messages

6. 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

- Official Documentation

- Issue Tracker

- Project Source

Thank you for your contributions!