docs: add ADR log and fork-maintenance canon#1
Merged
Conversation
docs/adr/ records cross-cutting decisions for the set in MADR style, with a
README index and seven backfilled records (overlay toolchain, hardened CI,
Lua 5.1 + FFI parens, unit = {}, AGENTS.md single source, annotated-tag
releases, treefmt formatting). CONTRIBUTING.md is the practical canon the
forks' AGENTS.md link to. Both state the read-before / write-after ADR
process. Docs only.
There was a problem hiding this comment.
Pull request overview
This PR introduces an ADR (Architecture Decision Record) log under docs/adr/ (MADR-style) and adds a root CONTRIBUTING.md that serves as the practical, cross-fork maintenance “canon” linking back to the ADR rationale.
Changes:
- Add
docs/adr/README.mdand seven initial ADRs documenting existing, cross-cutting decisions (toolchain, CI, Lua 5.1/FFI rules, unit representation, agent instructions, release process, formatting). - Add
CONTRIBUTING.mdas a concise, action-oriented maintenance guide for forks, with links to the ADRs.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/adr/README.md | Introduces the ADR directory, scope, maintenance rules, and ADR index. |
| docs/adr/0001-overlay-flake-toolchain.md | Documents the pinned toolchain approach via purescript-overlay. |
| docs/adr/0002-hardened-ci-canon.md | Documents the shared hardened CI workflow decisions and rationale. |
| docs/adr/0003-lua-51-target-and-ffi-parens.md | Documents Lua 5.1 target constraints and the FFI parenthesization requirement. |
| docs/adr/0004-unit-is-empty-table.md | Documents representing unit as {} rather than nil. |
| docs/adr/0005-agents-md-single-source.md | Documents the single-source agent-instructions file pattern. |
| docs/adr/0006-fork-release-by-annotated-tag.md | Documents the fork release process via annotated tags and set bump steps. |
| docs/adr/0007-formatting-treefmt-purs-tidy-lua-format.md | Documents formatter choices and treefmt-based formatting workflow. |
| CONTRIBUTING.md | Adds a practical fork-maintenance guide linking to ADR rationale. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+9
to
+10
| there. The existing fork tags (for example effect v4.1.0) are bare annotated | ||
| tags with no GitHub Release attached. |
| ## Commands | ||
|
|
||
| - Build: `nix develop -c ./scripts/build` | ||
| - Test: `nix develop -c bash ./scripts/test` (forks that ship Lua regression tests) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sets up a home for decisions that span the whole package set, plus the practical canon they back.
docs/adr/holds Architecture Decision Records in the MADR style (status, context, decision, consequences) with a README index. Seven records backfill the decisions already in force: the purescript-overlay toolchain, the hardened CI workflow, the Lua 5.1 target and the FFI parenthesisation rule,unit = {}, the AGENTS.md single-source pattern, the annotated-tag release process, and the treefmt formatting setup (purs-tidy plus lua-format, and why StyLua is out).CONTRIBUTING.mdis the do-this summary for maintaining a fork: toolchain, commands, the Lua 5.1 and FFI rules, CI, agent instructions, releasing. Each section links to the ADR that explains it. This is the page the forks'AGENTS.mdpoint at.Both the README and
CONTRIBUTING.mdspell out the process going forward: read the ADRs before a cross-cutting decision, add one after, and supersede rather than rewrite. Decisions about the pslua compiler itself stay in the pslua repository.Docs only.