Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (46 loc) · 3.43 KB

CONTRIBUTING.md

File metadata and controls

59 lines (46 loc) · 3.43 KB
Raw

Contributing to Polhem

How changes reach the repository, and who merges them, is in the contributing guide of the polhem-dev organization. This page adds what is specific to Polhem.

Read the developer documentation for the architecture, and the architecture decision records for why the design is the way it is.

Build and test

dotnet build Polhem.slnx --configuration Release
./test.sh
  • The build treats every warning as an error. Many code style rules are enforced through .editorconfig and the analyzers, so breaking them fails the build; the rest are described in .claude/rules/code-style.md.
  • ./test.sh starts local database containers when Docker has them, and runs all test projects. Tests that need a database are skipped when its connection string is not configured; the script header explains the container names and how to override them. Pass a test project path to run only that project.
  • If your change touches public API, declare it in the project's PublicAPI.Unshipped.txt and explain in the pull request whether it is binary-compatible. The analyzer only checks that a change is declared, not that it is compatible.
  • New public API comes with tests.

Conventions

  • Language: everything maintained together is in English: code, XML documentation, comments, test names and [DisplayName] text, and commit messages. User documents, written for developers who build applications with Polhem, are multilingual (English and Traditional Chinese); maintainer documents, the ADRs and this guide included, are English only. Some parts of the repository still contain Chinese from before this policy; write new content in English. The reasons are in ADR-045 and ADR-047.
  • Commit messages: English, in the imperative mood, with a subject that says what changed. Use the body to explain why.
  • Design decisions: a decision that others need to understand later is recorded as an ADR in maintainers/adr/.
  • Documents: after changing Markdown documents, run ./check-md-links.sh and ./check-public-docs.sh. English is the source of the documents under docs/<lang>/; ./check-docs-i18n.sh reports a Traditional Chinese translation that has fallen behind its source. If you cannot update the translation, say so in the pull request.
  • Personal working documents: plans, drafts and notes go in local/ at the repository root, which git ignores. Do not commit them, and do not link to them from committed files: nobody else can open them.

AI coding agents

Guidance for coding agents is in .claude/: .claude/CLAUDE.md, the rules in .claude/rules/ and the skills in .claude/skills/. It is committed and maintained like code, so it applies to every contributor who uses an agent. The rules there are also a detailed reference for the conventions above.

Releases

Maintainers publish releases. Pushing a v* tag publishes the packages to NuGet, and a published package cannot be withdrawn, so a tag is only pushed deliberately, after the release build and tests pass. Do not make a failing release build green by changing the tests or the code they check.

License

By contributing, you agree that your contributions are licensed under the MIT License.