Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (140 loc) · 5.32 KB

CONTRIBUTING.md

File metadata and controls

178 lines (140 loc) · 5.32 KB

Contributing Guidelines

Thank you for your interest in contributing to Starlette DI! Please take a moment to review this document before submitting a pull request.

Why should you read these guidelines?

Following these guidelines ensures that your contributions align with the project's standards, respect the time of maintainers, and facilitate a smooth collaboration process.

Ground Rules

Responsibilities

  • Ensure cross-platform compatibility for all changes (Windows, macOS, Debian, and Ubuntu Linux).
  • Follow the PEP 8 style guide and use single quotes (') for strings.
  • Adhere to clean code principles, such as SOLID, DRY, and KISS. Avoid unnecessary complexity.
  • Keep contributions small and focused. One feature or fix per pull request.
  • Discuss significant changes or enhancements transparently by opening an issue first.
  • Be respectful and welcoming. Follow the Python Community Code of Conduct.

Tools and Workflow

  • Use Ruff as the linter and formatter (Black could be an alternative).
  • Write NumPy-style docstrings for all public functions, classes, attributes, and properties.
  • Commit messages and pull requests must follow specific prefixes described here.

Your First Pull Request

Getting Started

If this is your first pull request:

Setup Instructions

  1. Fork the repository.
  2. Clone your fork to your local machine.
  3. Set up a virtual environment: 
    python -m venv venv
source venv/bin/activate  # on Windows: venv\Scripts\activate
  4. Install dependencies: 
    pip install -r requirements.txt
  5. Install ruff: 
    pip install ruff
  6. Run tests and Ruff linter formatter to confirm the setup: 
    python -m unittest discover -s tests -t .
python -m ruff check .

Reporting Issues

Security Issues

For security vulnerabilities, do not open an issue. Instead, email dairoandres123@gmail.com.

In order to determine whether you are dealing with a security issue, ask yourself these two questions:

  • Can I access something that's not mine, or something I shouldn't have access to?
  • Can I disable something for other people?

If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, just email dairoandres123@gmail.com.

Filing a Bug Report

When reporting a bug, please include:

  1. Python version.
  2. Operating system and architecture.
  3. Steps to reproduce the issue.
  4. Expected behavior.
  5. Actual behavior, including error messages and stack traces.

General questions should go to the python-discuss mailing list instead of the issue tracker. The Pythonists there will answer or ask you to file an issue if you have tripped over a bug.

Suggesting Features or Enhancements

To suggest a feature:

  1. Open an issue on the GitHub issues page.
  2. Clearly describe the desired feature, its purpose, and its expected behavior.
  3. If possible, include examples or PseudoCode.

Code Conventions

Code Style

  • Follow PEP 8 guidelines, enforced by Ruff and Black.
  • Use single quotes (') for strings unless escaping becomes cumbersome.
  • Write docstrings in NumPy style. Example: 
    def add(a: int, b: int) -> int:
    """
    Add two integers.

    Parameters
    ----------
    a : int
        First integer.
    b : int
        Second integer.

    Returns
    -------
    int
        Sum of the integers.
    """
    return a + b

Commit Message Format

  • Use a prefix to categorize your commit:
    • ci: for CI/CD changes.
    • test: Update tests/* files.
    • dist: Changes to dependencies, e.g. requirements.txt.
    • minor: Small changes.
    • docs: Updates to documentation. doc is also a valid prefix.
    • fix: Bug fixes.
    • refactor: Refactor of existing code.
    • nit: Small code review changes mainly around style or syntax.
    • feat: New features.
  • Examples: 
    feat: add support for previous versions of Python
fix: fix a bug in the module
ci: update the CI workflow
test: add tests for the new feature
docs: update the documentation

Pull Request Checklist

Before submitting a pull request:

  1. Add or update tests for your changes.
  2. Ensure all tests pass: 
    python -m pytest
  3. Check code linting: 
    python -m ruff check .
  4. Update the documentation, if necessary.
  5. Provide a clear and descriptive pull request title and description.

Pull requests titles should be short and descriptive, and should not exceed 72 characters. Also, must follow the specified commit message format.
⚡