Skip to content

Contribution Guidelines

Thank you for being interested in contributing to PyORlib! Your involvement is greatly appreciated ❤️

Getting Started

  Before creating an issue or pull request, please make sure to check if a similar discussion already exists. We encourage you to actively participate by engaging in existing issues.

Reporting Issues

  If you have any questions, bug reports, or feature requests, please open a new issue or discussion. When reporting issues, be sure to provide clear steps to reproduce the problem. For security vulnerabilities, please refer to our security policy.

Submitting Changes

  We greatly appreciate your contributions and want to ensure they align with the project's goals and quality standards. Unless your proposed change is trivial, such as fixing a typo or tweaking documentation, we recommend creating an issue or discussion to talk about the proposed change before submitting a pull request. This allows us to provide feedback, clarify requirements, and ensure your efforts are focused in the right direction. To make a contribution, please follow these steps:

  1. Fork the repository and create a new branch.
  2. Implement your changes in the branch.
  3. Ensure that formatting, linting, and tests pass.
  4. Whenever possible, include tests to cover the lines of code you added or modified.
  5. Commit your changes and submit a pull request with a clear, detailed message.

  We'll review your pull request to ensure it meets our quality standards before merging it into the main codebase. Please feel free to ask any questions along the way!

Development Setup

  We recommend developing in a virtual environment to isolate project dependencies. To set up your development environment, follow these steps:

  1. Create a virtual environment:

    python -m venv env

  2. Activate the virtual environment:

    source ./env/bin/activate

    .\env\Scripts\Activate.ps1

    source ./env/Scripts/activate

  3. Install development dependencies:

    pip install -e .[dev]

Running the Tests

During development, you have two options to run the test suite: 

pytest -v

hatch run tests:test

Checking Types

You can use the mypy tool to check the static typing of your code. Simply run the following command: 

mypy

hatch run tests:typing

Code Coverage

To check the code coverage of your changes, run the following command: 

coverage run -m pytest -v

hatch run tests:cov

PyORlib Documentation

  The documentation for our project is written in Markdown and built using Material for MkDocs. Additionally, the API documentation is generated from the docstrings using mkdocstrings. To begin working on the documentation in a development environment, simply execute the following command: 

mkdocs serve --dev-addr localhost:8000

hatch run docs:serve

Project Structure and Conventions

  This project follows the src-layout convention for Python packages. This convention improves code organization, facilitates easy testing and usage, and allows developers to install the package in editable mode. By adhering to this convention, we can validate the package thoroughly in a realistic environment, leading to a higher quality and user-friendly product.

Code Standards

We strive for a high-quality and maintainable codebase. To achieve this, we have established the following code standards:

  • PEP-8 Compliance ─ Please follow the guidelines outlined in PEP-8 for consistent code formatting. Adhering to these standards ensures readability and maintainability across our codebase.
  • Black Formatter ─ We recommend using the Black code formatter to ensure consistent style and formatting. By automatically enforcing a standard style, the Black formatter saves you time and effort in manual formatting.
  • Meaningful Naming ─ Use descriptive and meaningful names for variables, functions, and classes. Clear and intuitive naming enhances code comprehension, making it easier for everyone to understand and work with the code.
  • Modularity and Reusability ─ Encourage the development of modular and reusable code. Breaking down complex tasks into smaller, self-contained components promotes maintainability, reduces complexity, and allows for scalability and extensibility.
  • Optimization and Efficiency ─ Strive for efficient code by considering algorithmic complexity and optimizing where necessary. Writing code that is both correct and performant ensures responsive and scalable applications.

Documentation Style

  Clear and comprehensive documentation facilitates collaboration and understanding. When contributing to this project, please ensure that you document the following items using properly formatted docstrings:

  • Modules.
  • Class definitions.
  • Function definitions.
  • Module-level variables.

  PyORlib uses Sphinx docstrings formatted according to PEP 257 guidelines. For more examples and detailed guidance on using Sphinx-style docstrings, we encourage you to consult the official Sphinx documentation.

Pre-Submission Testing and Validation

  Before submitting your pull request, it is crucial to ensure that your changes pass all the necessary checks. To do so, simply run the following command: 

hatch run tests:all

  The above command will trigger the Hatch project manager to initiate the comprehensive testing process across all supported Python versions. It will run tests, perform typing checks, ensure code formatting, and measure code coverage. This ensures that your changes meet the required quality standards.

Testing for Individual Python Versions

If you want to test for specific Python versions, you can do so by specifying the desired versions in the command, as follows: 

hatch run +py=3.10 tests:all

hatch run +py=3.11 tests:all

Troubleshooting Hatch Environment Errors

If commands run successfully when executed manually but produce unexpected errors or misbehavior when run within a Hatch environment, even though the dependencies are declared correctly, this could indicate an issue with the Hatch environment cache. To resolve potential cache-related issues, you can remove the environment and clear its cache by running: 

hatch env remove [ENV_NAME]

Alternatively, you can remove all environments and their cache by running the following command: 

hatch env prune

Code of Conduct

  This project and everyone participating in it is governed by the PyORlib Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior.

Thanks in Advance!

  Thank you for considering contributing to this project. Your contributions are valuable and greatly appreciated. If you have any questions or need further clarification, please don't hesitate to reach out. We look forward to collaborating with you to enhance this project!