Contributor’s Guide

Welcome to the open source community building this toolkit! We’re thrilled you’re interested in contributing – your ideas and efforts are what make this project thrive.

We encourage you to explore the guide and familiarize yourself with our collaborative development process. If you have any questions or need help getting started, feel free to reach out on our GitHub issue tracker.

Be Courteous

In the spirit of collaboration, we emphasize the importance of maintaining a respectful and inclusive environment.

In this project, we uphold a golden rule that applies to all forms of contribution, including bug reports and feature requests: treat everyone involved with respect. We value the diverse perspectives and experiences of our contributors and encourage constructive and courteous interactions.

See the Code of Conduct for details.

Contribution Suitability

The final decision regarding the suitability of a contribution for the project rests with the project maintainers. While we carefully consider all contributions, there may be instances where certain contributions are not aligned with the project’s current goals or needs, and as a result, they may be declined.

Need some feedback on whether your idea is suitable for the project? Open a GitHub issue. We’re happy to discuss your ideas and provide feedback!

Code Contributions

Thinking about adding support for a new metadata standard? The section titled Shared Conversion Scripts provides a step-by-step guide.

Steps for Submitting Code

Here are a sequence of steps to help with your code contribution:

  1. Fork the project repository on GitHub.

  2. Create a feature branch from the main branch.

  3. Install the package by running uv sync --extra dev at the command line.

  4. Verify that all tests pass on your system by running uv run pytest at the command line. In case of failures, conduct a thorough investigation. If you require assistance in diagnosing the issue, follow the guidelines for filing Bug Reports.

  5. Construct test cases that effectively illustrate the bug or feature.

  6. Implement your changes, including any relevant documentation updates following our Documentation Contributions guidelines.

  7. Re-run the complete test suite to ensure the success of all tests.

  8. Format and analyze your code according to our Code Format and Analysis guidelines.

  9. Ensure the docs build following the Documentation Contributions guidelines.

  10. Commit your work following our Commit Messages guidelines.

  11. Submit a GitHub Pull Request to the main branch of the upstream repository.

Code Review

Once contributions have undergone a code review process, they will be merged. It is generally recommended to incorporate any feedback received during the code review, unless there are strong objections. If, after submitting your objections, it is determined that the original feedback is still applicable, you will have to either implement the suggested changes or retract your contribution.

Code Format and Analysis

Our project uses a couple tools to ensure the code base has a consistent style and format as it grows. We use ruff for code formatting and static code analysis. Both can be run from the command line:

uv run ruff format src/ tests/
uv run ruff check src/ tests/

Python Type Hints are used to improve static code analysis and code clarity.

Note, Ruff exceptions may be allowed. If you believe there is a valid reason to deviate from Ruff’s requirements for a specific piece of code, please open a GitHub issue to discuss and gain approval for the exception.

Documentation Contributions

We greatly appreciate any efforts to enhance the project documentation! The documentation files reside within the docs/ directory and are written in reStructuredText. We utilize Sphinx to generate a comprehensive suite of documentation. The API documentation is automatically generated by Sphinx from docstrings formatted according to PEP 287.

Build the docs from the command line:

uv run make --directory=docs clean html

Bug Reports

We value your help in improving this project! To avoid duplicate reports, it’s helpful to quickly check the existing GitHub issues to see if the bug has already been reported.

If you are reporting a bug, please use the Bug report issue template. We appreciate it!

Feature Requests

Feature requests help this project grow with the user community. If you have an idea for a new feature, we’d love to hear about it! Before submitting a feature request, we kindly request you to check the existing GitHub issues to ensure that the feature hasn’t been requested.

If you are proposing a feature, please use the Feature request issue template. Thanks!

Commit Messages

Commit messages are incredibly valuable for understanding the project’s code. When crafting your commit message, please provide context about the changes being made and the reasons behind them.

We use the Angular commit style. This allows Python Semantic Release to streamline the release process. Our project uses this style in full with the notable exceptions that the commit message header should not include the scope value, and that any related GitHub issues should be referenced. For example:

feat: add framework for new feature (#3, #5)

not

feat(module): add framework for new feature

Do your best to keep the commit message header from exceeding 52 characters in length, and the commit message body from exceeding 72 characters.