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.

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 (include steps to reproduce, expected/actual behavior, environment details)

  • Feature requests (include motivation, proposed API/usage, alternatives)

  • Questions (if you’re unsure whether something is a bug or feature request)

Contributor Workflow Quickstart (Codeberg + Forks + 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.og/BuffaloHerd/BuffaloBlueprint)

  • Click Fork

  • Choose your account as the destination

2) Clone your fork locally

Replace placeholders as needed:

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

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

git remote add upstream https://codeberg.og/BuffaloHerd/BuffaloBlueprint.git
git remote -v

The “5 Commands” Workflow (Every PR)

1) Sync your local main to 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

Generate a new project and check that the expected files are created and the project works as intended.

4) Add a Towncrier changelog fragment

Create exactly one file under newsfragments/ for each issue this PR addresses. (Note that one PR that addresses too many issues might need to be split into multiple PRs):

newsfragments/<ID>.<type>.md

  • <ID> is the issue number if you know it; otherwise use a placeholder like 000 and rename before merge.

  • <type> is one of:

    • feature — new user-facing capability (“Added …”)

    • bugfix — fix a user-visible defect (“Fixed …”)

    • doc — documentation changes (“Documented …”)

    • removal — removed/deprecated behavior (“Removed …”)

    • misc — small changes that don’t fit above but are still worth noting

Use the type that best matches what a user would care about. If you’re unsure:

  • Prefer bugfix when you corrected wrong behavior.

  • Prefer feature when you added new behavior.

  • Prefer misc for small user-facing improvements.

Example:

newsfragments/123.feature.md

Content: one short, user-facing sentence:

Added ability to regenerate settings with default values.

Check your news fragment using Towncrier:

uv run python -m towncrier check

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: https://codeberg.org/BuffaloHerd/BuffaloBlueprint branch main

  • Head: <your-username>/BuffaloBlueprint branch feature/<short-description>

Common Mistakes to Avoid

  • Committing directly to main (always use a branch)

  • Forgetting the newsfragments/ entry for user-facing changes

  • Writing fragments about internal refactors instead of user-visible outcomes

  • Opening a PR without running tests

Where to Find More Details

Licensing

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