Contributing Guidelines

How to report issues, propose changes, and submit pull requests to Buildish projects.

Thank you for considering contributing to Buildish. Contributions to code, docs, tests, examples, naming, onboarding, and project structure are all valuable.

Report bugs and request features

Open a GitHub issue in the most relevant Buildish repository.

  • For umbrella-project work such as the site, shared docs, or cross-component coordination, use the buildish-tooling/buildish repository.
  • For component-specific work, open the issue in that component’s repository.
  • If you are not sure where something belongs, email the development contact.

If you find a security vulnerability, do not open a public issue. Follow the Security guidance instead.

When filing an issue, include:

  • the affected repository, version, or branch,
  • the environment or platform involved,
  • what you did,
  • what you expected to happen,
  • and what actually happened.

Before you start coding

Review open issues and discuss your approach before starting a larger change. For substantial design changes, explain the intended approach in the relevant issue or by emailing the development contact before investing heavily in implementation.

Submit changes in a pull request

The best way to contribute changes is through a pull request against the relevant Buildish repository.

Recommended workflow:

  1. Fork the relevant repository on GitHub.
  2. Branch from that repository’s default development branch.
  3. Keep your change focused and easy to review.
  4. Run the relevant checks for the repository you changed.
  5. Open a pull request with a clear summary and rationale.

If the change corresponds to a GitHub issue, reference it in the pull request description with Fixes #123 or Related to #123.

For the aggregate Buildish repository, run the canonical gate from the repository root:

  • make check
  • make rat-check when adding files or changing legal material

For site-only iteration, cd site before running targets such as make test, make integration-test, or make build-local.

Working on a pull request

  • Add or update tests when behavior changes.
  • Rebase or otherwise refresh your branch if it falls behind the target branch.
  • Use draft pull requests for work in progress.
  • Be responsive to review feedback and resolve open questions before merge.

AI-assisted contributions

Contributors may use AI tools while preparing changes, but the person opening the pull request remains fully responsible for the contribution.

  • Understand the change end to end.
  • Be ready to explain and justify the implementation during review.
  • Ensure contributed material is compatible with the project’s licensing and contribution requirements.
  • Consider disclosing significant AI assistance in the pull request description for transparency.

Code contribution guidelines

  • Follow the existing style and structure of the repository you are changing.
  • Prefer small, reviewable pull requests over large unrelated batches.
  • Avoid unnecessary dependencies unless they have been discussed first.
  • Discuss public interfaces, extension points, or cross-component impact before requesting merge.
  • Give reviewers time to respond, especially for non-trivial changes.