Define Civic Infrastructure publication model

2026-09-30 13:42:29 -05:00
parent 1050560a75
commit 3f12cd221d
1 changed files with 291 additions and 0 deletions
@@ -0,0 +1,291 @@
 # Civic Infrastructure Publication Model
 ## 1. Purpose
 This specification defines the common publication model used by Civic Infrastructure components.
 Its purpose is to ensure that editable source material, public discussion, immutable publication, and publication history remain distinct while using the same vocabulary and conventions across services.
 This model may be used by Hubzilla, Portal, and other Civic Infrastructure components that publish durable public artifacts.
 ## 2. Roles of the Systems
 ### Gitea
 Gitea is the authoritative source repository for publication artifacts.
 It contains:
 - editable drafts;
 - revision history;
 - approved source material;
 - publication metadata;
 - publication records.
 Gitea is where a future revision is edited and tracked before publication.
 ### IPFS
 IPFS is the immutable publication layer.
 A published artifact placed on IPFS is identified by its CID.
 Published content is not modified in place. A changed artifact is published as a new object with a new CID.
 ### Human-Facing Service
 A service such as Hubzilla or Portal may present the current published artifact to users.
 The service may provide:
 - readable presentation;
 - explanation;
 - discussion;
 - comments;
 - links;
 - the current CID;
 - the current publication metadata.
 The human-facing representation is not itself the authoritative immutable publication unless it is the exact object identified by the published CID.
 ## 3. Defined Terms
 ### Draft
 A **Draft** is an editable artifact that has not yet been published as the current authoritative version.
 A Draft:
 - lives in Gitea;
 - may change;
 - may accumulate Git history;
 - may be reviewed and discussed;
 - does not yet have a publication CID.
 A Draft may identify the Published Version from which it descends.
 ### Published Version
 A **Published Version** is the exact approved byte sequence released as an authoritative Civic Infrastructure artifact.
 A Published Version:
 - is no longer edited in place;
 - has a Civic SHA-256 value;
 - has an IPFS CID;
 - has an associated Publication Record;
 - remains part of the permanent publication history after replacement.
 ### SHA-256
 The **SHA-256** value is the Civic Infrastructure cryptographic digest of the exact bytes of a Published Version.
 SHA-256 and CID are separate identities.
 The SHA-256 value identifies the exact published bytes using the Civic Infrastructure hashing convention.
 ### CID
 The **CID** is the IPFS content identifier assigned to the published object.
 A CID identifies specific content.
 If the content changes, the resulting publication has a different CID.
 A CID is never reassigned to changed content.
 ### Supersedes
 **Supersedes** expresses the relationship between a new Published Version and the earlier Published Version it replaces as the current operative version.
 Supersession does not delete, invalidate, or rewrite the earlier publication.
 The earlier publication remains historically valid as the version that existed during its applicable period.
 ### Publication Record
 A **Publication Record** is the structured record describing a Published Version.
 It records the identities and provenance necessary to identify and verify that publication.
 At minimum, a Publication Record should contain:
 - artifact identifier;
 - version;
 - publication status;
 - publication date;
 - SHA-256;
 - CID;
 - source Git commit;
 - predecessor or superseded version, when applicable.
 ## 4. Mutable Discussion and Immutable Publication
 Discussion and publication are separate functions.
 A human-facing post may be edited, commented upon, discussed, or replaced.
 The immutable Published Version identified by its CID is not altered by those activities.
 This distinction permits open discussion without sacrificing publication integrity.
 A discussion surface may therefore contain:
 - the readable current document;
 - comments;
 - questions;
 - proposed changes;
 - links to drafts;
 - the CID of the authoritative Published Version.
 The CID identifies the authoritative immutable publication, not the discussion surrounding it.
 ## 5. Publication Lifecycle
 The standard lifecycle is:
 1. Create or modify a Draft in Gitea.
 2. Review and discuss the Draft.
 3. Approve the Draft for publication.
 4. Freeze the exact publication bytes.
 5. Calculate the Civic SHA-256 value.
 6. Publish the exact bytes to IPFS.
 7. Obtain the CID.
 8. Create the Publication Record.
 9. Commit the Publication Record to Gitea.
 10. Update the relevant human-facing service with the Published Version and CID.
 11. Begin the next Draft when a future revision is required.
 ## 6. Replacement, Not Mutation
 Published artifacts are replaced, not rewritten.
 If any content of a Published Version must change:
 - the existing publication remains unchanged;
 - a new Draft is created;
 - the new Draft identifies the earlier Published Version;
 - the replacement is separately approved;
 - the replacement receives a new SHA-256;
 - the replacement receives a new CID;
 - the replacement receives a new Publication Record;
 - the replacement identifies the earlier version through `Supersedes`.
 The earlier version remains available as part of the publication history.
 ## 7. Draft Relationship to the Current Publication
 An editable Draft may record the CID of the current Published Version from which it descends.
 For example:
 ```text
 Artifact: hubzilla-terms-of-service
 Draft-Version: 1.1-draft
 Previous-Version: 1.0
 Previous-CID: bafy...
 Publication-CID: not assigned
 ```
 The Draft does not reuse the previous CID as its own publication identity.
 When the Draft becomes a Published Version, it receives its own CID.
 ## 8. Human-Facing Presentation
 A Hubzilla post, Portal page, or similar service may display the current Published Version for convenience.
 The presentation should clearly identify:
 - artifact name;
 - current version;
 - publication date;
 - SHA-256;
 - CID;
 - relationship to the prior version when applicable.
 The presentation should also make clear that the immutable artifact identified by the CID is the authoritative published object.
 The human-facing service may remain mutable so that discussion and explanatory material can continue around the publication.
 ## 9. Repository Convention
 The Civic Infrastructure publication repository should separate source artifacts from publication metadata.
 A standard structure may include:
 ```text
 artifacts/
    policies/
    trust/
    specifications/
 manifests/
 receipts/
 ```
 Draft and source material belong under `artifacts/`.
 Publication records and manifests belong under `manifests/` or another defined metadata location.
 Receipts or verification results belong under `receipts/`.
 ## 10. Publication Record Example
 A Publication Record may use a simple machine-readable format such as:
 ```yaml
 artifact: hubzilla-terms-of-service
 version: 1.0
 status: published
 published: 2026-09-30
 sha256: <sha256-value>
 cid: <ipfs-cid>
 source_commit: <git-commit>
 supersedes: null
 ```
 A replacement publication may record:
 ```yaml
 artifact: hubzilla-terms-of-service
 version: 1.1
 status: published
 published: <date>
 sha256: <new-sha256>
 cid: <new-cid>
 source_commit: <git-commit>
 supersedes:
  version: 1.0
  cid: <previous-cid>
 ```
 ## 11. Infrastructure-Wide Convention
 The terms defined in this specification should retain the same meaning across Civic Infrastructure components.
 In particular:
 - **Draft** always means editable and unpublished.
 - **Published Version** always means approved immutable publication.
 - **SHA-256** always identifies the exact published bytes using the Civic convention.
 - **CID** always identifies the IPFS publication object.
 - **Supersedes** always describes replacement without erasure.
 - **Publication Record** always records the publication identities and provenance.
 Individual services may present these concepts differently to users, but their meaning should not change.
 ## 12. Principle
 The Civic Infrastructure separates:
 **editing from publication, discussion from authority, and replacement from erasure.**
 This separation preserves both adaptability and historical integrity.