mirror of
https://github.com/storytold/craft-contrib.git
synced 2026-11-19 09:01:31 +01:00
RFC-0040: Shared-library-first guidance for Craft apps (#62)
This commit is contained in:
1 parent
cd77f54561
commit
937c37449f
3 files changed
+60
No files matched your search
@@ -1,5 +1,7 @@
|
||||
# RFC-0006: A shared section for coding agents (`AGENTS.md`)
|
||||
|
||||
Updated by: [RFC-0040](0040-shared-library-first-guidance.md)
|
||||
|
||||
Related: storytold/craft-libs#37, storytold/craft-libs#38.
|
||||
|
||||
## Summary
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# RFC-0040: Shared-library-first guidance for Craft apps
|
||||
|
||||
Updates: [RFC-0006](0006-coding-agents.md)
|
||||
|
||||
## Summary
|
||||
|
||||
Add one app-scoped rule to the canonical core house rules: before implementing
|
||||
reusable formats, codecs, protocols or UI, check craft-libs and relevant open
|
||||
work, then reuse or extend the shared API instead of keeping another app-local
|
||||
implementation. App-specific policy and model mapping remain in the app.
|
||||
|
||||
## Motivation
|
||||
|
||||
Separate guidance paragraphs in app AGENTS.md files can drift or contradict
|
||||
existing rules. One canonical rule, copied by the existing generated-block
|
||||
mechanism, makes the shared-library direction consistent without treating a
|
||||
new instruction as evidence that any existing cutover is complete.
|
||||
|
||||
## Decision
|
||||
|
||||
Add point 16 to `standards/house-rules-core.md`. Its scope is Craft apps even
|
||||
though the core block is also present in shared repositories. It preserves
|
||||
behavior, hostile-input/resource limits, attribution, layering and regression
|
||||
coverage. It does not authorize sibling-application crate dependencies, alter
|
||||
license/source allowlists or change platform requirements.
|
||||
|
||||
Existing maintainer-approved exceptions remain explicit local instructions.
|
||||
For example, an app-local parser selected by an accepted ADR is not silently
|
||||
replaced by this guidance; changing it requires the separate decision, code
|
||||
change and parity verification appropriate to that repository. A documented
|
||||
exception is not a reason to silently drop behavior during a cutover.
|
||||
|
||||
This changes contributor guidance, not application code or dependency pins.
|
||||
It does not declare any app or format migrated. The existing runtime-migration
|
||||
proposal [RFC-0036](https://github.com/storytold/craft-contrib/pull/56) addresses
|
||||
specific copies and their test suites; this RFC neither accepts its inventory
|
||||
nor replaces its migration decisions.
|
||||
|
||||
## Rollout
|
||||
|
||||
After the canonical change is merged, regenerate each app's applicable shared
|
||||
blocks from the merged source revision using the existing house-rules tool.
|
||||
Do not hand-edit generated blocks or stamp an unmerged source revision.
|
||||
Update existing guidance PRs rather than creating duplicate synchronization
|
||||
PRs. Remove redundant app-local copies of the common paragraph, while
|
||||
preserving local exceptions and app-specific restrictions.
|
||||
|
||||
Use the house-rules integrity check on each regenerated app file and review
|
||||
its full diff for unintended changes. No runtime validation is implied by the
|
||||
documentation check; code cutovers still need their own tests and reviews.
|
||||
|
||||
## Process
|
||||
|
||||
This adds a rule to the living document named by RFC-0006 and therefore follows
|
||||
[RFC-0013](0013-amending-rfcs.md), including this RFC-0006 back-link. Under
|
||||
RFC-0000 the normal comment period is three days; the maintainer/owner process
|
||||
remains unchanged.
|
||||
@@ -17,3 +17,4 @@ These apply in every Craft repository. A later rule may be stricter, not weaker.
|
||||
13. **Instructions must be readable by everyone.** No notes about one machine, and no links to files a reader cannot open. `craftrules` is retired. Do not link to it.
|
||||
14. **Keep pull requests moving.** Concurrent pull requests are fine; unanswered actionable feedback is not. Respond in 7 days, a reminder at 14, closure eligible at 30, from when an actionable request waits on the author. Suggestions and unconfirmed bot findings do not start the clock. A fix, explanation or agreed plan resets it; unrelated activity does not. Waiting on a reviewer or maintainer pauses it and does not count against the author. A maintainer decides closure; it is never automatic. Reuse search results, do not poll, and stop at a rate limit.
|
||||
15. **No agent attribution.** A pull request does not say an agent wrote it. A repository rule may not require that.
|
||||
16. **Shared libraries first for Craft apps.** Before adding or changing reusable file-format, codec, protocol or UI code, check `storytold/craft-libs` and relevant open pull requests. Reuse its public APIs or extend the appropriate shared library instead of duplicating an implementation in an app. Keep app-specific policy and model mapping local; preserve behavior, security and resource limits, attribution, layering and regression coverage. Document API gaps and maintainer-approved exceptions rather than silently dropping behavior. This does not authorize dependencies on sibling application crates or override existing platform, licensing or dependency-source requirements.
|
||||
Reference in new issue
Block a user