153 lines
7.5 KiB
Markdown
153 lines
7.5 KiB
Markdown
# Publish current CI badges through the assets mount
|
|
|
|
Apply this task to one repository at a time. Read the repository's local agent
|
|
instructions, inspect its existing CI and coverage setup, preserve unrelated
|
|
work, and follow its commit policy. Do not push or publish outside CI unless the
|
|
user explicitly requests it.
|
|
|
|
## Goal
|
|
|
|
Make the default branch expose three small, current SVG badges:
|
|
|
|
```text
|
|
<asset-mount>/coverage/<owner>/<project>/<default-branch>/version.svg
|
|
<asset-mount>/coverage/<owner>/<project>/<default-branch>/test.svg
|
|
<asset-mount>/coverage/<owner>/<project>/<default-branch>/coverage.svg
|
|
<asset-origin>/coverage/<owner>/<project>/<default-branch>/version.svg
|
|
<asset-origin>/coverage/<owner>/<project>/<default-branch>/test.svg
|
|
<asset-origin>/coverage/<owner>/<project>/<default-branch>/coverage.svg
|
|
```
|
|
|
|
Discover the canonical owner, project name, default branch, asset mount, and
|
|
public asset origin from repository or CI configuration. Do not infer them only
|
|
from the local checkout directory. Keep the default-branch component stable;
|
|
these URLs describe the latest default-branch build, not an immutable commit.
|
|
|
|
Retain only the three badges as Jenkins artifacts. Do not publish or retain
|
|
commit-addressed coverage directories, HTML, JSON, LCOV, or other detailed
|
|
reports unless the repository already has a separate requirement for them.
|
|
|
|
## CI behavior
|
|
|
|
1. Use the project's established test and line-coverage tools. Pin tools that
|
|
CI installs itself, and keep tool configuration in the conventional tracked
|
|
project file.
|
|
2. Enforce an honest coverage floor supported by useful behavior tests. Do not
|
|
exclude ordinary production code or distort code or tests to increase the
|
|
percentage.
|
|
3. Produce a temporary machine-readable coverage summary, extract and validate
|
|
a numeric percentage from 0 through 100, render `coverage/coverage.svg`, and
|
|
remove the summary.
|
|
4. Read the version from authoritative package or build metadata and render
|
|
`coverage/version.svg`. Do not duplicate the version in CI configuration.
|
|
5. Write a build-specific marker only after the test stage succeeds. In an
|
|
always-run cleanup action, render `coverage/test.svg` as `passing` only when
|
|
that marker exists; otherwise render it as `failing`. Remove the marker
|
|
afterward so an old workspace cannot affect a later build.
|
|
6. If coverage did not complete, render a neutral `-%` badge during cleanup.
|
|
Cleanup must run for both successful and failed builds so published status
|
|
cannot silently remain stale.
|
|
7. Archive exactly the three nonempty SVG files with fingerprinting on every
|
|
branch. Publish them only from the default branch. A missing or unwritable
|
|
publication mount is a CI failure.
|
|
8. Keep rendering and filesystem publication in small tracked scripts rather
|
|
than large Jenkins shell blocks. Use the repository's existing scripting
|
|
language when suitable; otherwise use portable POSIX `sh`.
|
|
|
|
Update the Jenkins success and failure summaries to mention tests, coverage,
|
|
badge generation, and any other gates that the pipeline actually runs.
|
|
|
|
## Renderer contract
|
|
|
|
Render badges locally and deterministically. Do not call an external badge
|
|
service.
|
|
|
|
- The version renderer accepts only characters valid for the project's version
|
|
format, grows the value segment for long versions, and enforces a sensible
|
|
minimum width.
|
|
- The test renderer accepts only `passing` or `failing` and selects green or
|
|
red respectively.
|
|
- The coverage renderer accepts `-` or a number from 0 through 100, rounds
|
|
numeric values, and selects documented green, yellow, red, or neutral colors.
|
|
- Reject invalid input before creating or replacing output.
|
|
- Escape all text inserted into XML.
|
|
- Center labels and values horizontally with `text-anchor="middle"`. In a
|
|
20-pixel badge, center text vertically at `y="10"` with
|
|
`dominant-baseline="middle"` instead of treating `y` as a font baseline.
|
|
- When POSIX `awk` prints a conditional expression, parenthesize it, for example
|
|
`print (width < 45 ? 45 : width)`, so the expression also works with FreeBSD
|
|
awk.
|
|
|
|
## Publication contract
|
|
|
|
The publication script receives the publication root and an explicit
|
|
allow-listed set of badge names. It must:
|
|
|
|
- require an absolute publication root and validate all arguments before
|
|
changing published state;
|
|
- create only the required owner, project, and default-branch directories;
|
|
- publish only `coverage.svg`, `test.svg`, and `version.svg` below the resolved
|
|
default-branch directory;
|
|
- verify every selected source badge exists, is a regular nonempty file, and is
|
|
not a symlink;
|
|
- migrate an old default-branch symlink by unlinking the symlink itself without
|
|
deleting its target, and reject any other non-directory branch destination;
|
|
- make directories mode `0755` and badges mode `0644` so the web server can
|
|
traverse and read them even under a restrictive umask;
|
|
- copy each badge to a temporary file in its destination directory and rename
|
|
it atomically over the public file;
|
|
- clean temporary files on ordinary failures and signals;
|
|
- quote paths and remain portable to the Jenkins worker's operating system;
|
|
- never recursively synchronize, prune, or delete the shared asset mount.
|
|
|
|
Do not automatically remove old commit-addressed directories. That is a
|
|
separate destructive migration requiring explicit authorization and exact path
|
|
verification.
|
|
|
|
## Repository updates
|
|
|
|
Place the live badges immediately below the README title, substituting the
|
|
resolved values:
|
|
|
|
```markdown
|
|

|
|

|
|

|
|
```
|
|
|
|
Do not link them to a report that CI does not retain. Document the local
|
|
coverage command, enforced floor, version source, temporary summary, archived
|
|
files, publication path, and public URLs. Remove tracked generated badge files
|
|
and obsolete status snapshots.
|
|
|
|
If this task also owns the web-server configuration, mount public assets
|
|
read-only, disable directory listing, serve SVG with a restrictive content
|
|
security policy, and revalidate or use a short cache lifetime for mutable badge
|
|
URLs. Otherwise record these as deployment requirements without expanding the
|
|
repository change into unrelated infrastructure work.
|
|
|
|
## Verification
|
|
|
|
Before committing:
|
|
|
|
1. Run the repository's formatting, build/check, test, lint, and supported
|
|
toolchain gates relevant to the change.
|
|
2. Run the exact CI coverage command and confirm the enforced floor.
|
|
3. Confirm the temporary summary yields a valid percentage, is removed, and
|
|
exactly three nonempty SVGs are selected for archival.
|
|
4. Exercise normal and long versions, passing and failing test states, green,
|
|
yellow, red, and neutral coverage, and invalid input rejection.
|
|
5. Parse every rendered file as XML and rasterize representative badges to
|
|
inspect text placement.
|
|
6. Test publication with `umask 077` against a temporary absolute root. Verify
|
|
modes, atomic replacement, idempotence, and old-symlink migration without
|
|
deleting the old target.
|
|
7. Verify rejection of missing badges, relative roots, unwritable
|
|
destinations, and regular-file branch destinations.
|
|
8. Validate Jenkins syntax as far as local tooling permits, inspect the final
|
|
diff, commit the change, and confirm the worktree is clean.
|
|
|
|
Report the measured coverage, enforced floor, checks run, commit ID, and any
|
|
checks unavailable locally. Do not claim the public badges are live until a
|
|
successful default-branch Jenkins build has published them.
|