Contributing to `objectory`¶

We want to make contributing to this project as easy and transparent as possible.

Overview¶

We welcome contributions from anyone, even if you are new to open source.

If you are planning to contribute back bug-fixes, please do so without any further discussion.
If you plan to contribute new features, utility functions, or extensions to the core, please first open an issue and discuss the feature with us.

Once you implement and test your feature or bug-fix, please submit a Pull Request.

Development Setup¶

Prerequisites¶

Python 3.10 or later
Git
uv for dependency management (recommended) or pip

Setting up your development environment¶

Fork the repository on GitHub

Clone your fork locally:

git clone git@github.com:YOUR_USERNAME/objectory.git
cd objectory

Set up the development environment:
```
make setup-venv
```

This will create a virtual environment and install all dependencies.

Activate the virtual environment:
```
source .venv/bin/activate
```
Install pre-commit hooks:
```
pre-commit install
```

Pull Requests¶

We actively welcome your pull requests.

Fork the repo and create your branch from main.
Make your changes with clear, descriptive commit messages.
If you've added code that should be tested, add tests.
If you've changed APIs, update the documentation.
Ensure the test suite passes:
```
make unit-test-cov
```
Make sure your code lints:
```
inv check-lint
```
Format your code:
```
inv check-format
```
Run the pre-commit hooks:
```
pre-commit run --all-files
```
Push to your fork and submit a pull request to the main branch.

Pull Request Guidelines¶

Keep pull requests focused on a single issue or feature
Write clear, descriptive commit messages
Include tests for new functionality
Update documentation as needed
Ensure all CI checks pass
Reference any related issues in the PR description

Code Style¶

This project follows these style guidelines:

Code formatting: Black with 100 character line length
Linting: Ruff
Docstrings : Google style
Type hints: Required for all public APIs

Pre-commit hooks will automatically check formatting and run linters.

Testing¶

Running Tests¶

Run all tests:

inv unit-test --cov

Writing Tests¶

Place tests in the tests/ directory
Use descriptive test names that explain what is being tested
Follow the existing test structure and patterns
Aim for high code coverage
Test edge cases and error conditions

Documentation¶

Building Documentation¶

Build the documentation locally:

cd docs
mike serve

Then open http://localhost:8000 in your browser.

Documentation Guidelines¶

Update docstrings for any changed functions/classes
Add examples to docstrings when helpful
Update user guide pages for API changes
Keep documentation clear and concise

Issues¶

We use GitHub issues to track public bugs or feature requests.

Reporting Bugs¶

When reporting bugs, please include:

A clear, descriptive title
Steps to reproduce the issue
Expected behavior vs actual behavior
Python version and objectory version
Minimal code example that demonstrates the issue
Error messages and stack traces (if applicable)

Feature Requests¶

For feature requests, please include:

A clear, concise description of the feature
Motivation: why is this feature needed?
Use case examples
Proposed API or implementation (if applicable)
Any alternatives you've considered

Code Review Process¶

A maintainer will review your PR
You may be asked to make changes
Once approved, a maintainer will merge your PR

Please be patient - maintainers review PRs as time permits.

Community Guidelines¶

Be respectful and constructive
Welcome newcomers and help them get started
Focus on the code, not the person
Assume good intentions

We follow the Code of Conduct.

Release Process¶

Releases are handled by maintainers:

Update version in pyproject.toml
Create a git tag
Publish to PyPI
Update documentation

Getting Help¶

Check the FAQ
Browse existing issues
Open a discussion

License¶

By contributing to objectory, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.

Contributing to objectory¶