Contributing¶

We welcome contributions and volunteers for the project! Please read the following guidelines before contributing.

Issues¶

Questions, bug reports, and feature requests are welcome as discussions or issues. Please search the existing issues before opening a new one. To report a security vulneratbility, please see the security policy.

To help us resolve your issue, please provide the following information:

Expected behavior: A clear and concise description of what you expected to happen.
Actual behavior: A clear and concise description of what actually happened.
Steps to reproduce: How can we reproduce the issue?
Environment: Include relevant details like the operating system, Python version, and any other relevant information.

Pull Requests¶

We welcome pull requests for bug fixes, new features, and improvements. We aim to provide feedback regularly and will review your pull request as soon as possible.

Unless your change is not trivial, please create an issue before submitting a pull request. This will allow us to discuss the change and ensure it aligns with the project goals.

Prerequisites¶

You will need the following to start developing:

Python 3.10+
virtualenv, poetry, or pipenv for the development environment.
git for version control.
make for running the Makefile commands.

Installation & Setup¶

Fork the repository on GitHub and clone your fork locally. Then, install the dependencies:

# Clone your fork and cd into the repo directory
git clone git@github.com:<your username>/PyJAS.git
cd PyJAS

# Install the dependencies
# e.g., using poetry
poetry install

# Setup pre-commit
make pre-commit-setup

Checkout a New Branch¶

Create a new branch for your changes:

# Create a new branch
git checkout -b my-new-feature

Run Tests, Linting, Formatting, Type checking, & Pre-Commit Hooks¶

Before submitting a pull request, ensure that the tests pass, the code is formatted correctly, and the code passes the linting and type checking checks:

# Run tests
make test

# Run linting & formatting
make lint
make format
make check-types

# Run pre-commit hooks
make pre-commit

Build Documentation¶

If you make changes to the documentation, you can build the documentation locally:

# Build the documentation
make serve-docs

Commit and Push your Changes¶

Commit your changes, push to your forked repository, and create a pull request:

Please follow the pull request template and fill in as much information as possible. Link to any relevant issues and include a description of your changes.

When your pull request is ready for review, add a comment with the message "please review" and we'll take a look as soon as we can.

Code Style & Conventions¶

Documentation Style¶

Documentation is written in format and follows the Markdown Style Guide. Please ensure that the documentation is clear, concise, and easy to read. API documentation is generated using mkdocs & mkdocstrings. We follow google-style docstrings.

Code Documentation¶

Please ensure that the code is well-documented and easy to understand when contributing. The following should be documented using proper docstrings:

Modules
Class Definitions
Function Definitions
Module-level Variables

PyJAS uses Google-style docstrings according to PEP 257. Please see the example for more information.

Class attributes and function arguments should be documented in the style of "name: description" & include an annotated type and return type when applicable. Feel free to include example code in docstrings.