Add the documentation of metrics-usage

Publish the documentation of perses/metrics-usage from v0.8. The repository
has no release branch, so releaseBranch is now optional: without it, every
minor version is taken from its latest patch tag.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

Author: Nexucis

AGENTS.md

@@ -45,9 +45,10 @@ Before editing, read `README.md` for the local setup, the organization of the co
   `perses.yaml`, `prometheus.yml`, `scripts/generate_config.sh`, the other services of `docker-compose.yaml`.
 
 The documentation is not written here. It is pulled at build time from perses/perses, perses/perses-operator,
-perses/helm-charts and perses/plugins (`docs/` of each repository). Versioned sources publish every minor version from
-its release branch `release/vX.Y`, or its latest patch tag. Fix the content of the documentation in its repository,
-and the navigation in the `docs/nav.yaml` of that repository; `content/nav/` is only a fallback for old versions.
+perses/helm-charts, perses/plugins and perses/metrics-usage (`docs/` of each repository). Versioned sources publish
+every minor version from its release branch `release/vX.Y`, or its latest patch tag. Fix the content of the
+documentation in its repository, and the navigation in the `docs/nav.yaml` of that repository; `content/nav/` is only a
+fallback for old versions.
 
 ## Engineering rules
 

README.md

@@ -53,9 +53,10 @@ It contains:
 - the home page, the adopters page and the blog, written in this repository (`content/`),
 - the documentation of [perses/perses](https://github.com/perses/perses),
   [perses/perses-operator](https://github.com/perses/perses-operator),
-  [perses/helm-charts](https://github.com/perses/helm-charts) and [perses/plugins](https://github.com/perses/plugins),
-  pulled from these repositories at build time. Perses and the operator are versioned: every minor version is
-  published (from the release branch when it exists, the latest patch tag otherwise),
+  [perses/helm-charts](https://github.com/perses/helm-charts), [perses/plugins](https://github.com/perses/plugins) and
+  [perses/metrics-usage](https://github.com/perses/metrics-usage), pulled from these repositories at build time.
+  Perses, the operator and metrics-usage are versioned: every minor version is published (from the release branch
+  when it exists, the latest patch tag otherwise),
 - the download pages, built from the latest GitHub releases. In the browser, the pages also check GitHub for the
   releases published since the build and display them (cached 10 minutes; if GitHub is not reachable or rate limits
   the visitor, the releases of the build are displayed).

src/content/config.server.ts

@@ -23,7 +23,8 @@ const linkSchema = z.object({
 
 const versioningSchema = z.object({
   minVersion: z.string().regex(/^v\d+\.\d+$/, 'minVersion must look like vX.Y'),
-  releaseBranch: z.string().default('release/v{major}.{minor}'),
+  // Without release branch, each minor version is taken from its latest patch tag.
+  releaseBranch: z.string().optional(),
 });
 
 const sourceSchema = z

src/content/sync.server.ts

@@ -81,7 +81,10 @@ export async function downloadDocs(source: SourceConfig, sha: string, destinatio
 
 async function resolveSource(source: SourceConfig): Promise<Omit<ManifestVersion, 'dir'>[]> {
   if (source.versioning) {
-    const output = await lsRemote(source.repository, ['--tags', '--heads']);
+    const output = await lsRemote(
+      source.repository,
+      source.versioning.releaseBranch === undefined ? ['--tags'] : ['--tags', '--heads'],
+    );
     return resolveVersions(parseLsRemote(output), source.versioning);
   }
   const branch = source.branch ?? 'main';

src/content/versions.server.test.ts

@@ -69,6 +69,14 @@ describe('resolveVersions', () => {
     expect(versions).toEqual([{ id: 'v1.2', ref: 'release-1.2', sha: 'b', release: 'v1.2.0' }]);
   });
 
+  it('uses the latest patch tag of every version without release branch', () => {
+    const versions = resolveVersions(refs, { minVersion: 'v0.54' });
+    expect(versions).toEqual([
+      { id: 'v0.55', ref: 'v0.55.1', sha: 'fff1', release: 'v0.55.1' },
+      { id: 'v0.54', ref: 'v0.54.0', sha: 'ggg1', release: 'v0.54.0' },
+    ]);
+  });
+
   it('rejects an invalid minimum version', () => {
     expect(() => resolveVersions(refs, { minVersion: '0.53', releaseBranch: 'release/v{major}.{minor}' })).toThrow('invalid minor version');
   });

src/content/versions.server.ts

@@ -84,13 +84,14 @@ function compareSemver(a: Semver, b: Semver): number {
  * resolveVersions computes the list of published versions of a source, sorted from the most recent to the oldest.
  * Only minor versions having at least one final release (no pre-release) are published, so a release branch
  * created for a release candidate doesn't appear before the release is out.
+ * Without releaseBranch, every version is taken from its latest patch tag.
  */
 export function resolveVersions(
   refs: GitRef[],
-  options: { minVersion: string; releaseBranch: string },
+  options: { minVersion: string; releaseBranch?: string },
 ): ResolvedVersion[] {
   const min = parseMinorVersion(options.minVersion);
-  const branchMatcher = branchRegexp(options.releaseBranch);
+  const branchMatcher = options.releaseBranch === undefined ? undefined : branchRegexp(options.releaseBranch);
   const latestTags = new Map<string, { semver: Semver; ref: GitRef }>();
   const branches = new Map<string, GitRef>();
 
@@ -108,7 +109,7 @@ export function resolveVersions(
       }
       continue;
     }
-    const branch = branchMatcher.exec(ref.name);
+    const branch = branchMatcher?.exec(ref.name);
     if (branch?.groups) {
       branches.set(`v${Number(branch.groups.major)}.${Number(branch.groups.minor)}`, ref);
     }

website.yaml

@@ -49,7 +49,7 @@ docs:
       legacyPath: perses/docs
       versioning:
         # Each minor version is published. The docs are taken from the release branch when it exists,
-        # otherwise from the latest patch tag.
+        # otherwise from the latest patch tag. Without `releaseBranch`, only the tags are used.
         minVersion: v0.53
         releaseBranch: release/v{major}.{minor}
     - id: operator
@@ -75,6 +75,14 @@ docs:
       docsDir: docs
       legacyPath: plugins/docs
       branch: main
+    - id: metrics-usage
+      title: Metrics Usage
+      description: Track the usage of metrics across dashboards, alerting rules and recording rules.
+      repository: perses/metrics-usage
+      docsDir: docs
+      versioning:
+        # No release branch: each minor version is taken from its latest patch tag.
+        minVersion: v0.8
 
 blog:
   title: Perses Blog