Contributor’s Guide

Welcome—and thank you for considering contributing to geoenv! 🤗

We’re excited to have you here. Whether you’re fixing a bug, improving docs, or proposing a new feature, your contributions make this project better.

Got a question or idea? Start a conversation in our GitHub issues!

Be Respectful

We’re committed to creating a friendly, welcoming space for collaboration.

Please be kind and constructive in all interactions. Diversity of background, perspective, and experience strengthens our community.

See our Code of Conduct for details.

Is Your Idea a Good Fit?

Not sure if your idea fits the project? Let’s talk! 💡

Open a quick GitHub issue and we’ll help you assess it. While we thoughtfully review every suggestion, the maintainers ultimately determine what aligns with the project goals.

How to Contribute Code

Here’s a simple guide to submitting a pull request 🛠:

  1. Fork the repo.

  2. Create a new feature branch off main.

  3. Install the project with uv: uv sync --extra dev

  4. Run the tests: uv run pytest Investigate and fix any failures.

  5. Add test cases to support your change.

  6. Make your changes. Update docs where relevant (see Improving the Documentation).

  7. Re-run tests to confirm everything still works.

  8. Format and lint your code (see Code Style & Linting).

  9. Build the docs: uv run make --directory=docs clean html

  10. Write a good commit message (see Writing Good Commit Messages).

  11. Open a Pull Request targeting the main branch.

We’ll review your submission and may offer suggestions. Once everything looks good—it’s in!

Code Style & Linting

To keep the codebase consistent 🧹, we use ruff for automatic formatting and static code analysis.

Run both with:

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

Improving the Documentation

We love doc updates! 📘

The docs live in the docs/ directory and use Sphinx + reStructuredText.

To build them locally:

uv run make --directory=docs clean html

API docs are generated from PEP 287-style docstrings.

Bug Reports

If you find a bug 🐛, we want to hear about it! First, check the GitHub issues to see if it’s already been reported.

If it’s new, please use the Bug report issue template.

Feature Requests

Got an idea for a feature ✨? Let’s explore it! Before submitting, please search existing GitHub issues.

To propose something new, use the Feature request template.

Writing Good Commit Messages

We value small, focused commits and transparent development practices. ✍🏽

A good commit message explains what changed and why.

We recommend:

  • Limit the header to 52 characters or less.

  • Wrap the body at 72 characters.

  • Follow the Angular style format.

Example:

feat: add new feature to improve performance

This feature optimizes the algorithm for better speed.
It reduces the time complexity from O(n^2) to O(n log n).

Closes #123

Thank you again for contributing to geoenv 💚. You help make open science more powerful and more connected.