We treat every issue as a problem statement, following Extreme Programming. The title states the problem; the body describes it; an optional suggestion section proposes how it might be fixed.
Phrase the title as a problem statement, not a solution or action.
- Good:
Query params with null values cause 500 errors - Bad:
Add null handling to query params
## Problem
What is wrong. How to reproduce. Symptoms, error messages, relevant file paths.
## Suggestion
Optional. How the fix could be approached. Omit the section entirely if you have no concrete suggestion.
Keep ## Problem concrete: how to reproduce, observed vs expected behaviour. Two sections only.
MAGIC is a monorepo. Every issue should carry one or more comp: labels naming the top-level directories it touches:
comp:clojure-runtimecomp:magic-runtimecomp:magecomp:magic-compilercomp:nostrandcomp:magic-unitycomp:unity-examples
PRs target the develop branch. main only receives merges from develop via release PRs.
Same format as a commit title:
<prefix>(<scope>): <short description>
Keep it to one line.
Closes #<issue-number>
---
- First change description
- Second change description
Reference the issue with Closes #<n> in the description so GitHub closes it when the change reaches main. Keep bullets short; the issue carries the full context.
We follow Conventional Commits:
<prefix>(<scope>): <description>
Common prefixes: feat, fix, refactor, docs, test, chore. Keep the title to one line; details belong in the PR description.
Reference the related GitHub issue in the title or body, e.g. (#42) or Closes #42.
When a source change touches a stdlib namespace or magic-compiler internals, the committed .clj.dlls under nostrand/references/ and magic-unity/Runtime/Infrastructure/Export/ need a paired refresh commit:
chore(bootstrap): refresh <name> DLL for <short reason> (#<issue>)
This keeps the committed binaries in lockstep with their sources.