Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ Versions follow the compatibility policy in the
- Widened `R08`: where a shared pipeline the repository documents builds and
publishes its releases, that pipeline's own verifiable record (for a macOS app,
the Developer ID signature and notarization) is sufficient evidence of origin.
- Widened `R03`: a shared release pipeline started for a specific tag counts as
automation; the tag push does not have to start it.
- Widened `R01`: where the manifest format has no field for a property, the
artifact's own metadata file (for an application, `Info.plist`) is its home.
- Released as minor: these changes widen a criterion, so a recorded `Fail` may now
be a `Pass` and no recorded `Pass` can weaken, under
[Versioning And Compatibility](docs/repository-quality-standard.md#versioning-and-compatibility).
Expand Down
18 changes: 16 additions & 2 deletions docs/repository-quality-standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -364,15 +364,29 @@ instead.

| ID | Requirement | Expected evidence |
|---|---|---|
| <a id="r01"></a>R01 | Package metadata is complete and agrees with repository metadata | Package manifest |
| <a id="r01"></a>R01 | Package metadata is complete and agrees with repository metadata, in the package manifest or, where the manifest format has no field for a property, in the artifact's own metadata | Package manifest, plus the artifact's metadata file for whatever the manifest cannot hold |
| <a id="r02"></a>R02 | Versioning and compatibility policy are documented | README or release guide |
| <a id="r03"></a>R03 | A tag produces installable artifacts through automation | Release workflow and uploaded release assets |
| <a id="r03"></a>R03 | A tag produces installable artifacts through automation: a workflow the tag triggers, or a shared release pipeline run for that tag | Release workflow, or the shared pipeline's documented run, and the uploaded release assets |
| <a id="r04"></a>R04 | Tag, package version, and release title are consistent | Release workflow validation |
| <a id="r05"></a>R05 | A built artifact has been smoke-tested as a consumer receives it: the published file installed and launched, and its core function exercised. The result is recorded | A workflow that does it, or a dated record naming the version tested and what was exercised |
| <a id="r06"></a>R06 | Release notes describe meaningful changes and upgrade concerns | GitHub release or changelog |
| <a id="r07"></a>R07 | Release notes are generated from the changelog entry for the version being released, and automation fails the release when that entry is missing, empty, or still held in an unreleased section | Release workflow gate, in this repository or in a shared release pipeline this repository documents, plus a published release whose notes match its changelog entry |
| <a id="r08"></a>R08 | A consumer can verify that a published artifact came from this repository or from the shared release pipeline that publishes its releases, or the repository states why they cannot | Registry provenance, a build attestation, the shared pipeline's documented and verifiable record, or a recorded statement |

`R01` is about where the metadata lives, not about whether it exists. Some
manifest formats have no field for a licence, a repository URL, or a description
(SwiftPM is one). Where that is so, the metadata belongs in the file the artifact
itself carries, such as an application's `Info.plist`, and the repository states
which properties live where. The criterion is met when every property has a home
and the homes agree; a property with none is not.

`R03` asks that the artifact comes from automation rather than from a maintainer's
machine, and that a tag identifies exactly what was built. It does not require the
tag push itself to start the build. A shared release pipeline that a maintainer
starts for a specific tag, builds from that tag's pinned commit, and publishes to
the release qualifies, when the repository documents the command that starts it.
A build made locally and uploaded by hand does not.

`R06` and `R07` divide the work. `R06` is about content: notes a reader can act
on. `R07` is about provenance: the notes a consumer actually receives are the
maintained entry for that exact version, and not a second description written at
Expand Down
8 changes: 4 additions & 4 deletions standard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -208,16 +208,16 @@ criteria:
evidence: "Runbook or explicit not-applicable result"
- id: "R01"
section: "Package And Release Repositories"
requirement: "Package metadata is complete and agrees with repository metadata"
evidence: "Package manifest"
requirement: "Package metadata is complete and agrees with repository metadata, in the package manifest or, where the manifest format has no field for a property, in the artifact's own metadata"
evidence: "Package manifest, plus the artifact's metadata file for whatever the manifest cannot hold"
- id: "R02"
section: "Package And Release Repositories"
requirement: "Versioning and compatibility policy are documented"
evidence: "README or release guide"
- id: "R03"
section: "Package And Release Repositories"
requirement: "A tag produces installable artifacts through automation"
evidence: "Release workflow and uploaded release assets"
requirement: "A tag produces installable artifacts through automation: a workflow the tag triggers, or a shared release pipeline run for that tag"
evidence: "Release workflow, or the shared pipeline's documented run, and the uploaded release assets"
- id: "R04"
section: "Package And Release Repositories"
requirement: "Tag, package version, and release title are consistent"
Expand Down
Loading