CONTRIBUTING.md

Contributing to python-sage-imap

Thank you for considering contributing to python-sage-imap! We welcome contributions from the community to help make this project better.

Table of Contents

• Contributing to python-sage-imap
  • Table of Contents
  • Getting Started
  • Running Tests
  • Code Style
  • Security Checks
    • Running Bandit
  • Pre-commit Hooks
    • Setting Up Pre-commit Hooks
  • Submitting a Pull Request
  • Reporting Issues
  • Additional Resources

Getting Started

1. Fork the repository on GitHub:

   Go to the python-sage-imap repository and click on the "Fork" button in the top-right corner.

2. Clone your fork locally:

   git clone https://github.com/your-username/python-sage-imap.git
   cd python-sage-imap

3. Install dependencies using Poetry:

   If you don't have Poetry installed, you can install it by following the instructions on the Poetry website.

   poetry install

4. Create a new branch for your feature or bugfix:

   git checkout -b feature/your-feature

Running Tests

We use pytest for testing. To run the tests, execute:

poetry run pytest

Ensure that all tests pass before submitting a pull request.

Code Style

We use black and isort to format our code. Please ensure your code is formatted correctly before submitting a pull request:

poetry run black .
poetry run isort .

Additionally, we use flake8 and pylint for linting. You can run these tools to check for code style issues:

poetry run flake8
poetry run pylint django_sage_email

Security Checks

We use bandit to perform security checks on our codebase. Bandit helps identify common security issues in Python code.

Running Bandit

To run Bandit with the current configuration:

poetry run bandit -c pyproject.toml

Pre-commit Hooks

We use pre-commit to ensure code quality and consistency. Pre-commit hooks will run automatically before each commit to check and format the code.

Setting Up Pre-commit Hooks

1. Install pre-commit:

   poetry add --dev pre-commit

2. Install the pre-commit hooks:

   poetry run pre-commit install

3. Run pre-commit hooks manually (optional but recommended before committing):

   poetry run pre-commit run --all-files

The pre-commit configuration is defined in the .pre-commit-config.yaml file. Make sure to review and understand the hooks configured.

Submitting a Pull Request

1. Commit your changes:

   Write clear and descriptive commit messages. Follow the guidelines in the Conventional Commits specification if possible.

   git commit -am 'feat: add new email feature'

2. Push to the branch:

   git push origin feature/your-feature

3. Open a pull request on GitHub:

   Go to the original repository on GitHub and open a pull request. Provide a clear and descriptive title and description for your pull request. Link to any relevant issues or discussions.

4. Wait for review:

   One of the project maintainers will review your pull request. Be responsive to feedback and be prepared to make changes if necessary.

Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub. Provide as much detail as possible to help us understand and address the issue:

1. Go to the Issues section of the repository.
2. Click on "New issue".
3. Fill out the issue template with relevant details.

Additional Resources

• Poetry Documentation
• Black Documentation
• isort Documentation
• pytest Documentation
• flake8 Documentation
• pylint Documentation
• Pre-commit Documentation

Thank you for contributing!