Matsubaa/FedDIY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add project revision lifecycle details and clarify versioning model in documentation

Browse Source
This commit is contained in:
Kyle J. Turpin
2026-05-23 18:01:57 -05:00
parent 5ca022074d
commit e20669e42a
2 changed files with 18 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+15
View File
@@ -40,6 +40,21 @@ Current product definition:
- Materials are also an extensible entity: the core material record captures display name, quantity, and unit; domain-specific attributes (yarn weight, fibre content, filament diameter/material, wood species/grade, electronics component value/package) are carried in extension payloads on the material entry, using the same extension mechanism as project-level extensions.
- A federated material catalog is a long-term goal: community-defined material types and shared taxonomy entries could be federated as ActivityPub objects, allowing instances to reference a common vocabulary without requiring central authority.
### Project Revision Lifecycle
FeDIY uses a hybrid draft + immutable revision model:
- **Drafts are mutable working copies.** Authors edit a draft until they publish it.
- **Publishing creates an immutable numbered revision.** A publish action snapshots the complete project state: materials, tools, steps, media references, canonical links, extension payloads, and any referenced sub-project pointers.
- **Revisions are append-only.** Once published, a revision never changes. Corrections or updates are made by creating a new draft from the latest published revision.
- **Revision numbering is monotonic per project.** Revision 1 is the first published snapshot; later publishes increment the number.
- **History is first-class.** The API and UI expose the full revision history by default, with the latest published revision presented as the canonical current view.
- **Draft visibility is restricted.** Drafts are visible only to the author and explicitly authorized collaborators; they are not part of public history until published.
- **Supersession is explicit.** A newly published revision supersedes the previous published revision, but the older revision remains addressable for audit, attribution, and history browsing.
- **Project references are recursive by graph, not by inline body embedding.** A project may reference another project as a sub-process or prerequisite (for example taco recipe -> taco meat recipe). The reference resolves to a specific published revision, so downstream recipes remain stable even if the referenced project is later updated.
- **Cycle detection is required.** The system must prevent or safely collapse cyclic project-reference graphs so recursive composition cannot create infinite expansion in the API or UI.
- **Extension payloads are versioned with the revision.** A revision snapshot includes extension data as it existed at publish time so clients can render or compare historical states accurately.
## Client and Front-End Strategy
The server exposes a stable, documented HTTP API as its primary interface. The bundled web UI is a first-party client of that same API — it receives no privileged server-side access that a third-party client could not also use.