Contribute to PauLie#

We welcome contributions from everyone! By participating in PauLie, you agree to follow our guidelines.

  1. As stated in Getting started, ensure you have Python 3.12 or higher installed on your machine or in a virtual environment.

  2. You requires to install uv to manage the dependencies of PauLie.

  3. Make sure you have a GitHub account.

  4. Fork the repository on GitHub.

  5. Clone your fork locally:

git clone https://github.com/QPauLie/PauLie.git

  1. Navigate to your local clone PauLie reprository:

cd PauLie

  1. Install dependencies with uv:

uv sync --all-extras --dev

uv will create a virtual environment and install all dependencies there. You are now ready to run, test, and develop the project.

Making changes#

  1. Before starting to create your ideas, make sure that your fork in up to date with the original PauLie repository:

git fetch upstream
git checkout main
git merge upstream/main

  1. Create your feature or idea on your local fork. It’s best to make changes on a dedicated branch, with the branch name reflecting the feature or fix you are adding.

  2. Include tests and documentation for new features. If you’re adding a new feature, ensure you provide test cases and update the documentation. See Adding a New Feature for a detailed checklist.

  3. When the code is ready to go, make sure you run the test suite using pytest, ruff, etc.

  4. Open a pull request (PR) on your local fork. When your feature is ready for review, go to your fork of PauLie on GitHub and open a PR. Any subsequent commits to that branch will automatically be added to the open PR. This will commit your feature to the branch of your local fork.

  5. Open a pull request on original fork. Once your changes are ready for merging, go to the original PauLie on GitHub. Then, open PR, selecting “compare across fork” to submit your changes from your fork’s branch, and add a comment indicating that your code is ready for review. The code will be reviewed after the continuous integration (CI) workflow passes and the primary developer approves the review.

Adding New Features#

The new feature should follow these guidelines:

  1. The function docstring should follow the Google style as outlined in References in Docstrings.

  2. The docstring for a new feature must include:

    • A theoretical description of the feature.

    • One or more examples in an Examples subsection.

    • A References subsection.

  3. All added lines must be covered by tests and appear in the pytest code coverage report. See Testing for more details.

  4. The code and unit tests for the new feature should follow the Code Style guidelines, using ruff for lint checking.

  5. The new feature must be added to the __init__.py file of its module to avoid import issues.

  6. If the new feature introduces a new module, it must be listed in docs/autoapi_members.rst so that it appears on the API Reference page via sphinx-autoapi.

Before submitting a pull request, please make sure your changes pass all tests.

Public API Contributions#

The PauLie public API defines the symbols users should import directly from paulie or curated subpackages. This ensures stability, discoverability, and consistent documentation.

Policy#

  1. Only curated symbols are public:

    • Expose classes, functions, and constants intended for common use.

    • Internal helpers remain private.

  2. Explicit exports:

    • All public API is defined and curated in modules paulie/__init__.py using __all__.

  3. Deprecation:

    • Deprecated symbols are handled via __getattr__ and warnings.warn(DeprecationWarning)

Adding a New Symbol#

  1. Check that the new feature is commonly used or essential for end users.

  2. Add it to the curated API in src/paulie/__init__.py:

from .common import new_function

__all__ = ["new_function", ...]

  1. Add symbol in src/tests/test_pulic_api.py:

import paulie

public_symbols = ["new_function", ...]

  1. If replacing a symbol, include a deprecated_symbols.

Functional Testing#

Ensure that both pytest and pytest-cov are installed on your machine. If they are not installed, follow the installation instructions for pytest and pytest-cov.

To verify that your code is working correctly, run the following commands in the PauLie directory:

uv run pytest -q

The pytest module is used for running tests, and pytest-cov can generate local code coverage reports. Code coverage can be checked using the --cov-report=term-missing option in pytest-cov.

Any changes to an existing module should have corresponding tests placed in its tests directory (e.g., PauLie/tests/test_module.py).

Lint Checking#

Formatting and linting are handled using ruff. To install ruff, refer to the official ruff installation instructions.

To detect errors and style issues such as unused imports, undefined variables, style violations, and complexity problems, run:

uv run ruff check

To verify that your code is formatted according to Ruff’s formatter rules, run:

uv run ruff format --check

Note: without the --check option, ruff format will modify your code automatically.

For deeper static analysis and design-level checks, we use pylint.

To lint the source code, test scripts, and examples without installing pylint, run:

uvx pylint "src/**/*.py" "tests/**/*.py" "examples/**/*.py"

Document Building#

The sphinx is used in PauLie to build the HTML documentation, use:

uv run sphinx-build -b html -W docs/source docs/_build/html