Contributing

Thanks for contributing! This project is hosted on Codeberg (Forgejo). We use a fork + pull request workflow and require small changelog fragments for most changes. If you would like to contribute with code, documentation, testing, or other activities we welcome the help.

Ground Rules

  • Be respectful and constructive.

  • Keep changes focused and reasonably scoped.

  • Follow the repository Code of Conduct.

Where to Ask Questions / Report Problems

Use the repository Issues tracker for bug reports, feature requests, and questions.

Bug Reports

Please include:

  • What you expected to happen

  • What actually happened

  • Steps to reproduce (minimal example if possible)

  • Environment details (OS, Python version, package versions, etc.)

  • Logs/tracebacks and screenshots if relevant

Suggestions / Feature Requests

Please include:

  • The problem you’re trying to solve and why it matters

  • A proposed solution (or a couple of options)

  • Any constraints (API stability, performance, dependencies)

  • Links/references if applicable

Questions

If you’re unsure whether something is a bug or a feature request, open an issue and describe what you’re seeing.

Contribution Workflow Quickstart (Codeberg + Fork + PRs)

This is the minimal workflow we expect from contributors (students included). It assumes you are contributing via a fork on Codeberg and opening a pull request into the upstream main branch.

One-Time Setup (First Contribution)

1) Fork the repository on Codeberg

  • Open the upstream repo (e.g. https://codeberg.org/BuffaloHerd/BuffaloExample)

  • Click Fork

  • Choose your account as the destination

2) Clone your fork locally

Replace placeholders as needed:

git clone https://codeberg.org/<your-username>/BuffaloExample.git
cd BuffaloExample

Add the upstream (main) repo so you can stay in sync:

git remote add upstream https://codeberg.org/BuffaloHerd/BuffaloExample.git
git remote -v

The “5 Commands” Workflow (Every PR)

1) Sync your fork with upstream

Before starting new work make sure your repo is update-to-date:

git checkout main
git fetch upstream
git pull --ff-only upstream main
git push origin main

2) Create a feature branch

Do not work directly on main:

git checkout -b feature/<short-description>

where <short-description> is the feature branch name that should briefly encapsulate the purpose of this branch.

3) Make changes and run checks

As you develop new code, make sure you are adding tests into the tests directory. There should be tests that cover all code paths as well as additional tests for corner-cases, common use cases, and other verification testing scenerios.

Run the test/check suite locally before opening a PR:

./scripts/run_test_matrix.sh

(Use any additional repo-specific commands documented in the additional development documentation.)

4) Add a Towncrier changelog fragment

PRs need to have at least one changelog fragment file under newsfragments/ that indicates what issue (or issues) this PR is addressing. See the towncrier PR workflow for details.

5) Push your branch and open a PR

Push to your fork:

git push -u origin feature/short-description

Then open a pull request on Codeberg:

  • Base repo: https://codeberg.org/BuffaloHerd/BuffaloExample

  • Base branch: main

  • Head repo: <your-username>/BuffaloExample

  • Compare branch: your feature branch

Style / quality expectations

  • Keep public APIs stable unless explicitly changing them.

  • Update docstrings/docs when behavior changes.

  • Make sure code has type hinting.

  • Add/adjust tests when behavior changes.

Licensing

By contributing, you agree that your contributions will be licensed under the repository’s license.