Contributing

Thank you for your interest in contributing to django-custom-storage! This document provides guidelines and instructions for contributing.

Code of Conduct

This project adheres to the Python Software Foundation's Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Development Setup

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/django-custom-storage.git
cd django-custom-storage

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install development dependencies:
```
pip install -e ".[testing,linting]"
```
Install pre-commit hooks:
```
pre-commit install
```

Running Tests

Run the test suite:

python runtests.py

Run tests for specific Django/Python versions using tox:

tox

Run tests for a specific environment:

tox -e py310-django52

Code Quality

Before submitting code, ensure:

All tests pass: python runtests.py
Code passes linting: flake8 src tests
Code is formatted: black src tests
Imports are sorted: isort src tests
Type checking passes (if applicable): mypy src

The project uses: - Black for code formatting - isort for import sorting - flake8 for linting - mypy for type checking (optional)

Making Changes

Development Workflow

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Make your changes and write/update tests
Ensure all tests pass and code quality checks pass

Commit your changes:

git add .
git commit -m "Add feature: your feature description"

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub

Commit Messages

Follow these guidelines for commit messages:

Use clear, descriptive commit messages
Start with a capital letter
Use imperative mood ("Add feature" not "Added feature")
Keep the first line under 72 characters
Add more detailed explanation if needed in the body

Example:

Add support for Django 5.2

- Update get_storage_class to use import_string for Django 5.2+
- Add tests for Django 5.2 compatibility
- Update tox.ini to include Django 5.2 test environments

Pull Request Guidelines

When creating a Pull Request:

Describe your changes: Provide a clear description of what your PR does
Reference issues: If your PR fixes an issue, reference it (e.g., "Fixes #123")
Add tests: Include tests for new features or bug fixes
Update documentation: Update relevant documentation if needed
Keep PRs focused: One PR should address one issue or feature
Ensure CI passes: All CI checks must pass before merge