Contributing to OrganiserPro

Thank you for your interest in contributing to OrganiserPro! We welcome contributions from everyone, whether you’re a developer, designer, writer, or just someone with a good idea.

Ways to Contribute

There are many ways to contribute to OrganiserPro:

  • Code contributions: Fix bugs, implement new features, or improve existing code

  • Documentation: Improve documentation, fix typos, or add examples

  • Bug reports: Report bugs you find while using OrganiserPro

  • Feature requests: Suggest new features or improvements

  • Testing: Help test the software and report issues

  • Community: Help answer questions on issue trackers or forums

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/your-username/OrganiserPro.git
cd OrganiserPro

  3. Set up the development environment:

    # Create and activate a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package in development mode with all dependencies
pip install -e .[dev]

  4. Create a new branch for your changes:

    git checkout -b your-feature-branch

  5. Make your changes and ensure tests pass:

    # Run tests
pytest

# Check code style
black OrganiserPro tests
isort OrganiserPro tests
flake8 OrganiserPro tests

  6. Commit your changes with a clear message:

    git commit -m "Add your commit message here"

  7. Push to your fork and submit a pull request

Coding Standards

  • Follow PEP 8 style guidelines

  • Use type hints for all functions and methods

  • Write docstrings for all public functions, classes, and modules

  • Keep lines under 88 characters (Black’s default line length)

  • Write tests for new features and bug fixes

  • Document all new features and changes

Commit Message Guidelines

  • Use the present tense (“Add feature” not “Added feature”)

  • Use the imperative mood (“Move cursor to…” not “Moves cursor to…”)

  • Limit the first line to 72 characters or less

  • Reference issues and pull requests liberally after the first line

  • Consider starting the commit message with an applicable emoji: - :bug: :bug: when fixing a bug - :sparkles: :sparkles: when adding a new feature - :memo: :memo: when writing docs - :art: :art: when improving the format/structure - :zap: :zap: when improving performance - :white_check_mark: :white_check_mark: when adding tests - :wrench: :wrench: when updating configuration - :recycle: :recycle: when refactoring code - :fire: :fire: when removing code or files - :lock: :lock: when dealing with security - :arrow_up: :arrow_up: when upgrading dependencies - :arrow_down: :arrow_down: when downgrading dependencies

Testing

We use pytest for testing. To run the tests:

# Run all tests
pytest

# Run tests with coverage
pytest --cov=OrganiserPro

# Run a specific test file
pytest tests/test_something.py -v

# Run a specific test function
pytest tests/test_something.py::test_function_name -v

Documentation

We use Sphinx for documentation. To build the documentation:

# Install documentation dependencies
pip install -e .[docs]

# Build the documentation
cd docs
make html

# Open the documentation in your browser
open _build/html/index.html

Code Review Process

  1. Create a pull request (PR) with your changes

  2. Ensure all CI checks pass

  3. A maintainer will review your PR and provide feedback

  4. Address any feedback and update your PR

  5. Once approved, a maintainer will merge your PR

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See code_of_conduct for more information.

License

By contributing to OrganiserPro, you agree that your contributions will be licensed under the MIT License.