How to Contribute to Herbie: Process and Guidelines for Developers

Developers can contribute to Herbie by starring the repository, participating in GitHub Discussions, opening issues for bugs or features, and submitting pull requests that include tests and documentation updates.

The Herbie project (blaylockbk/herbie) is a Python library for downloading meteorological data, and it relies on community contributions to improve its functionality and documentation. Whether you are fixing a bug, adding a new weather model accessor, or improving docstrings, following the established contribution workflow ensures your changes are reviewed and merged efficiently.

Getting Started with the Herbie Contribution Process

Before writing code, engage with the community to understand current priorities and avoid duplicate effort.

Show Interest and Join the Community

Start by clicking the ⭐ Star button on the repository and selecting Watch to receive updates. Join the GitHub Discussions board, particularly the Show and Tell category, where contributors share workflows and use cases. This visibility helps maintainers recognize active community members.

Report Issues and Propose Features

Open an Issue to report bugs, request features, or suggest documentation improvements. The maintainer tracks all enhancements through the Issues tab, making it the appropriate venue to propose significant changes before investing development time. For minor documentation tweaks or questions, start a discussion thread instead.

Step-by-Step Contribution Workflow

The Herbie contribution process follows a standard GitHub fork-and-branch workflow. According to the README's Contributing section [lines 68‑81 of README.md](https://github.com/blaylockbk/herbie/blob/main/README.md#L68-L81), contributors should follow these specific steps:

Fork and Clone the Repository

Create your own fork of the repository, then clone it locally:

git clone https://github.com/<your-username>/herbie.git
cd herbie

Create a Feature Branch

Never commit directly to the main branch. Create a descriptive branch name:

git checkout -b feature/add-gfs-analysis

Implement Changes and Follow Code Standards

Modify code within the src/herbie/ directory, which contains the core library including model accessors and utilities. Maintain PEP 8 style consistency. The project uses automated linting tools, so ensure your code passes style checks before submitting.

Write Tests for New Functionality

All new functionality must include corresponding tests placed under the tests/ directory. Existing tests must continue to pass. You can run the test suite locally using:

pytest -q

Submit a Pull Request

Push your branch to your fork and open a Pull Request against blaylockbk/herbie:main. The PR template will prompt you to describe your changes. The maintainer reviews all submissions, and once approved, merges them into the main branch.

Key Files and Directories for Contributors

Understanding the repository structure accelerates the contribution process:

• README.md – Contains the contribution checklist and community links lines 68‑81
• docs/user_guide/housekeeping/disclaimer.md – Brief contributing guide lines 1‑8
• src/herbie/ – Core library source code where model implementations and accessors reside
• tests/ – Unit-test suite that validates functionality and prevents regressions
• .github/workflows/ – CI pipelines that automatically run pytest and style checks on every PR

Local Development and CI Requirements

Herbie uses GitHub Actions for continuous integration. Before submitting your PR, verify that your changes pass local validation to avoid CI failures:

# Run the test suite

pytest -q

# Check code style (if ruff or black are installed)

ruff check src/
black --check src/

The CI pipelines in .github/workflows/ automatically execute these checks when you open a pull request. Keeping the CI checks green is essential for a smooth review process.

Summary

• Engage first: Star the repo, watch for updates, and join GitHub Discussions before coding
• Document intent: Open an Issue for bugs or features to track your contribution
• Follow the workflow: Fork, branch, code, test, and submit a PR against the main branch
• Maintain quality: Write tests in tests/ and ensure existing tests pass with pytest -q
• Respect CI: Verify style compliance locally to avoid automated check failures
• Reference authoritative sources: Consult README.md lines 68‑81 and docs/user_guide/housekeeping/disclaimer.md for the official guidelines

Frequently Asked Questions

What is the first step to contribute to Herbie?

Start by starring the repository and joining the GitHub Discussions board to engage with the community. The README's Contributing section lines 68‑81 recommends this engagement before writing code to ensure alignment with project goals.

Where are the contribution guidelines documented?

The primary guidelines appear in two locations: the README's Contributing section and the concise guide in docs/user_guide/housekeeping/disclaimer.md lines 1‑8. Both documents outline the expectation to open Issues, write tests, and submit Pull Requests for review.

What testing requirements exist for Herbie contributions?

All new functionality must include unit tests placed in the tests/ directory. Contributors must ensure existing tests continue to pass by running pytest -q locally. The test suite validates that changes do not break existing weather model accessors or download functionality.

How does the pull request review process work?

After you push your feature branch and open a PR, the maintainer reviews the code for correctness, style compliance, and test coverage. Automated CI pipelines in .github/workflows/ run the full test suite and linting checks. Once the maintainer approves the changes and all checks pass, they merge the PR into the main branch.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}