Changes for content/handbook/engineering/architecture/design-documents/release_manifest/_index.md: 24 added lines, 2 removed lines.
Original line number
Diff line number
Diff line
@@ -79,7 +79,7 @@ It will contain two pieces:
## Data Model
{{% alert %}}
When the data model is finalized, the below entry will be converted into a [JSON Schema](https://json-schema.org/) which can be used for automatic validation of data in CI.
The data model below is published as a [JSON Schema](https://gitlab.com/gitlab-org/release/manifests/schema/-/blob/main/json-schemas/release-manifest.schema.json). Both manifest projects validate every file against it in CI. See [Storage](#storage) for the projects.
{{% /alert %}}
### Mutable Catalog
@@ -145,10 +145,32 @@ Once the release 19.5.0 is published to users, we will combine the version infor
```
## Storage
The release manifest lives in three dedicated projects under `gitlab-org/release/manifests`. Module authors and consumers start here.
| Project | Contents | Visibility |
| --- | --- | --- |
| [`manifests/unreleased`](https://gitlab.com/gitlab-org/release/manifests/unreleased) | Mutable catalog. One file per component, at `{major}/{minor}/{patch}/{module-id}.json` | Private. Internal consumers ask the Delivery: Release and Deploy team for a group share with the Reporter role |
| [`manifests/released`](https://gitlab.com/gitlab-org/release/manifests/released) | Immutable record. One file per published GitLab release, at `{major}/{minor}/{patch}.json` | Public |
| [`manifests/schema`](https://gitlab.com/gitlab-org/release/manifests/schema) | The [JSON Schema](https://gitlab.com/gitlab-org/release/manifests/schema/-/blob/main/json-schemas/release-manifest.schema.json) that both tiers validate against | Public |
Nobody pushes to `main` in either data project directly: the push allow-list on `main` holds only the release automation bots. A human change has to go through a merge request, where the CI checks gate it. Both projects validate every file against the schema. The record project also fails any merge request that changes a record file which already exists, enforcing the "immutable once published" goal (see [Goals](#goals)) by mechanism rather than by convention. A deliberate corrective change is still possible: it needs the `record-change-approved` label, and the job then passes and posts an audit comment naming the changed files.
### How Entries Are Written
Two separate events write to the release manifest, and each one writes to a different project.
**A module publishes a version.**[release-tools](https://gitlab.com/gitlab-org/release-tools) adds that module's entry to the [mutable catalog](https://gitlab.com/gitlab-org/release/manifests/unreleased), for each GitLab version that is still upcoming. The write does not wait for a GitLab release, and it does not touch any other module. This keeps the module release cycle independent of the GitLab release schedule (see [Goals](#goals)).
**A GitLab version publishes.** release-tools freezes the catalog entries for that version into one file in the [immutable record](https://gitlab.com/gitlab-org/release/manifests/released), then carries the same entries forward into the catalog for the next versions. The frozen file is the answer for that GitLab version from then on, and it never changes.
Carrying entries forward keeps the last published version of a module in the catalog until the module publishes again. A module that releases rarely still appears in later records, and a module that publishes during the cycle replaces the entry.
