Skip to content
Snippets Groups Projects
Commit bfbe8ef7 authored by Rasmus Dahlberg's avatar Rasmus Dahlberg
Browse files

Merge branch 'rgdd/release-docs' into 'main'

Add release documentation for the docs component

See merge request !30
parents 96d4781d fdba0356
Branches
Tags
1 merge request!30Add release documentation for the docs component
Pipeline #4163 passed
# ST Documentation releases
Our goal is to provide comprehensive, clear, and up-to-date documentation for all components within the ST ecosystem. This includes detailed API references, user guides, installation manuals, and more, designed to support both new and experienced users and contributors.
# Releases of docs
## What is being released
Each release of ST Documentation includes updates across various components. These may consist of:
- The Hugo source code of the entire repository, except for the
`content/docs/archive` directory which contains outdated material. Some
outdated material may also be lingering in the `static` directory.
- New features or components added to the ecosystem.
- Updates to existing documentation, including improvements and bug fixes.
- Enhanced tutorials and guides, aligned with the latest release numbers.
What changed in each release is documented in a [NEWS](./NEWS) file. The NEWS
file also specifies which other System Transparency components are meant to be
used when building the site with content copied straight into the Hugo tree.
Releases are announced on our dedicated mailing list and through our project communication channels. The [NEWS file](NEWS.md) documents the user-visible changes for each release, the recommended approach to using the documentation, and any relevant updates.
Note that a release is simply a signed git-tag with a matching NEWS entry,
accessed from the [docs][] repository. There are no release emails on the
[st-announce][] list because they would mostly be 1:1 with collection releases.
Note: This release is marked by a git-tag, and further updates may occur between this and subsequent major releases. These intermediate updates are intended for early adopters and may not always carry full support.
To verify tag signatures, get the allowed-ST-release-signers file published at
the [signing-key page][], and verify the tag vX.Y.Z using the following command:
The ST Documentation project is focused on providing clear, comprehensive documentation for the ST ecosystem. While the information is freely available for use, our primary support is directed towards users engaging with the documented interfaces and guides as presented.
git -c gpg.format=ssh -c gpg.ssh.allowedSignersFile=allowed-ST-release-signers tag --verify vX.Y.Z
We encourage users to engage with the documentation as a guide to understanding and utilizing the ST ecosystem effectively.
The above configuration can be stored permanently using `git config`.
## What release cycle is used
Users are mainly expected to interact with released versions of the docs
component as part of collection releases and `docs.system-transparency.org`.
As this is an initial release, a regular release cycle has not yet been established. Future releases will be guided by user feedback, development progress, and the need for updates.
[docs]: https://git.glasklar.is/system-transparency/project/docs
[st-announce]: https://lists.system-transparency.org/mailman3/postorius/lists/st-announce.lists.system-transparency.org/
[signing-key page]: https://www.system-transparency.org/keys/
Critical bug fixes and essential updates will be released as needed. We aim to ensure that the documentation remains up-to-date and useful for all users.
## Release testing
## Upgrading from a previous release
See the [test docs](./docs/testing-docs.md) for information on how we check that
the site in this repository builds and works as expected.
Given that v0.1.0 is the initial release, there are no prior versions to upgrade from. Future releases will include detailed instructions on how to transition or update your understanding based on the new documentation.
## What release cycle is used?
The [NEWS file](NEWS.md) will be an essential resource for understanding changes and updates between releases. It will highlight any significant changes, new additions, or shifts in documentation strategy.
We make releases when new documentation is ready and meant for rendering at
`www.docs.system-transparency.org`. In other words, a releases of the docs
component is tightly coupled with a corresponding [collection release][].
## Expected changes
[collection release]: ./content/docs/releases/collection-release.md
For the upcoming period following this initial release:
## Upgrading
- Focus will primarily be on bug fixes and minor enhancements which include the completion of guides and tutorials.
- The documentation may receive updates for clarity, additional examples, and expansion of existing sections based on user feedback and evolving needs.
- Tasks for the next release can be found in the [Getting Started Milestone](https://git.glasklar.is/groups/system-transparency/-/milestones/16).
The internal structure of the Hugo tree may be changed across releases without
warning. For example, files and directories could be deleted or moved. If you
depend on docs from anywhere but `docs.system-transparency.org/st-vX.Y.Z`, then
ensure to pin the version with a git-commit or git-tag to avoid breakage. Refer
to the git-history and the NEWS file to figure out how to upgrade appropriately.
# Release checklist
## Making a release
- [ ] docs/release-checklist.md looks reasonable
- [ ] docs/testing-docs.md looks reasonable
- [ ] RELEASES.md is up-to-date, see expectations below
- [ ] README.md is up-to-date
- [ ] Create a pre-release tag
- [ ] All release tests pass, see [test docs][]
- [ ] After finalizing the NEWS file (see expectations below), create a new
signed tag. Usually, this means incrementing the third number for the most
recent tag that was used during the above release testing.
[test docs]: ./testing-docs.md
[st-announce]: https://lists.system-transparency.org/mailman3/postorius/lists/st-announce.lists.system-transparency.org/
## RELEASES-file
- [ ] What in the repository is released and supported
- [ ] The overall release process is described, e.g., where are releases
announced, how often do we make releases, what type of releases, etc.
- [ ] The expectation we as maintainers have on users is described
- [ ] The expectations users can have on us as maintainers is
described, e.g., what we intend to (not) break in the future or any
relevant pointers on how we ensure that things are "working".
## NEWS-file
- [ ] The previous NEWS entry is for the previous release
- [ ] Explain what changed, e.g., specification updates, major additions or
reorganization, etc.
- [ ] List which components the site was build-tested with
Note that the NEWS file is created manually from the git-commit history.
# Testing docs
This file documents how docs is tested:
- Checked-in content is up to date
- The site builds as expected
We do these tests before cutting a docs release. Be warned that there is no
automation, and that there is a degree of subjectivity involved here.
## Checked-in content is up to date
Check that any checked in reference documentation is consistent. For example,
there are no inconsistencies between the host configuration, trust policy, and
OS package documentation.
Check that any checked in guides work by trying them interactively. For
example, the quickstart guide works when following it step-by-step.
Make an overhaul of any other checked in content. Ensure that nothing is
obviously wrong or particularly unhelpful.
## The site builds as expected
We check that it is possible to build the site in the context of a collection
release. Ensure there is a pre-release tag of docs, clone the release
engineering repository, and create a manifest with the components under test.
$ git clone https://git.glasklar.is/system-transparency/core/system-transparency.git /tmp/st
$ cd /tmp/st
$ (cd collection-releases && cp v1.0.0.manifest vX.Y.Z.manifest)
Edit the copied manifest file to list the appropriate component versions.
Create the tarball. Use the force flag to allow not having signatures.
$ ./releng/mk-release-archive.sh -f -o /tmp/st-vX.Y.Z collection-releases/vX.Y.Z.manifest
You should see that `/tmp/st-vX.Y.Z{,.tar.gz}` was created. Now we are ready to
test that the site builds as expected with the listed manifest components.
$ cd /tmp/st-vX.Y.Z/docs
$ git submodule update --init --recursive
$ ./assemble.sh
$ hugo serve
The site is being rendered at http://localhost:1313. Eyeball all pages from
start to finish. In particular, check that:
- [ ] There are no empty pages
- [ ] There are no placeholder pages that were not substituted
- [ ] All links work (click them)
- [ ] Links to material that is rendered on the site use relative filenames,
i.e., when clicking such links the site continues to be browsed locally.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment