Define Civic Infrastructure publication model
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user