Contribution Guidelines¶

Thank you for being interested in contributing to Pyventus! In this section, you will discover how to effectively contribute to this project, as well as best practices for reporting issues, submitting pull requests, and engaging with the community ❤️

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 the Pyventus 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:

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

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

Development Setup¶

To ensure that project dependencies are isolated and do not interfere with other projects, we recommend using a virtual environment for development. To set up a new virtual environment, please follow these steps:

Create a new virtual environment with:
```
python -m venv venv
```

Activate the environment with:

macOS Windows Linux

. venv/bin/activate

. venv/Scripts/activate

. venv/bin/activate

Install development dependencies with:
```
pip install -e .[dev]
```

Running Tests¶

To run the test suite of Pyventus, you can either perform a manual execution with pytest or use Hatch to run the test suite across all supported Python versions.

Manual Using Hatch

pytest -v

hatch run tests:test

Code Coverage¶

To evaluate the test coverage of your code, you can either perform a manual evaluation with Coverage.py or use Hatch to evaluate test coverage across all supported Python versions.

Manual Using Hatch

coverage run -m pytest -v

hatch run tests:cov

Checking Types¶

To check the static typing of your code, you can either perform a manual check with mypy or use Hatch to check static typing across all supported Python versions.

Manual Using Hatch

mypy

hatch run tests:typing

Linting and Formatting¶

To check the linting and formatting of your code, you can either manually use Ruff or use Hatch to perform these checks across all supported Python versions.

Manual Using Hatch

ruff check & ruff format --check

hatch run tests:style

Pyventus Documentation¶

The Pyventus documentation is written in Markdown and built with Material for MkDocs. To get started in development mode, run one of the following commands:

Manual Using Hatch

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¶

At Pyventus, ensuring a high-quality and maintainable codebase is essential. Therefore, the following code standards have been established to guide the development process as well as promote consistency:

PEP-8 Compliance ─ Follow the guidelines outlined in PEP-8 to ensure clean and readable Python code. Adhering to these standards promotes consistency, enhances code comprehension, and facilitates collaboration among contributors.
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.

Class Structure ─ While there are no strict rules for structuring classes in Python beyond common sense and readability, Pyventus has established a recommended class structure that provides a foundation for a consistent codebase.(1)

Recommended Class Structure

Class Name

1. Inner Classes and Class Attributes
   └── Access Modifiers: private, protected, public

2. Static Methods
   ├── @staticmethod
   └── Access Modifiers: private, protected, public

3. Class Methods
   ├── @classmethod
   └── Access Modifiers: private, protected, public

4. Special Attributes
   ├── __slots__, __init__, __repr__

5. Properties
   ├── @property
   └── Access Modifiers: private, protected, public

6. Abstract Methods
   ├── @abstractmethod
   └── Access Modifiers: private, protected, public

7. Instance Methods
   └── Access Modifiers: private, protected, public

8. Other Magic Methods

Documentation Style¶

When contributing to Pyventus, please make sure that all code is well documented. The following should be documented using properly formatted docstrings:

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

Pyventus uses Sphinx docstrings formatted according to PEP 257 guidelines. For more examples and detailed guidance on using Sphinx-style docstrings, please refer to the official Sphinx documentation.

Pre-Submission Testing and Validation¶

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

hatch run tests:all

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

Testing for Specific Python Versions

Python 3.10 Python 3.11 Python 3.12 Python 3.13

hatch run +py=3.10 tests:all

hatch run +py=3.11 tests:all

hatch run +py=3.12 tests:all

hatch run +py=3.13 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, if you prefer to take a more comprehensive approach by removing all environments and clearing their caches, you can do so by running the following command:

hatch env prune

Code of Conduct¶

This project is committed to fostering a welcoming and inclusive environment for all participants. The Pyventus Code of Conduct applies to this project and everyone involved in it. By participating, you agree to uphold these standards and contribute to a positive experience for everyone.

If you witness or experience any unacceptable behavior, we encourage you to report it to the project maintainers. Your feedback is important in helping us maintain a respectful community.