Skip to content

docs: make coverage README contributor-focused and quality-first - #16

Merged
vitormattos merged 2 commits into
mainfrom
docs/quality-first-contribution-readme
Nov 8, 2026
Merged

vitormattos merged 2 commits into
mainfrom
docs/quality-first-contribution-readme

Conversation

@vitormattos

@vitormattos vitormattos commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Why

The previous README led with GitHub Actions implementation details, data retention, hosting, and licensing. That made it difficult for a new contributor or an organization using LibreSign to understand the purpose of the coverage project.

Coverage is a diagnostic signal—not a quality target in isolation. The landing page of this repository should guide developers toward meaningful tests and improvements to the LibreSign PHP application.

Changes

  • Rewrite the README around the value of trustworthy document-signing workflows, prioritizing observable behavior, regression prevention, meaningful assertions, authorization/error boundaries, and maintainable tests.
  • Add a prominent, concrete path for developers: explore coverage → identify a worthwhile test/issue → consult LibreSign's contribution and testing guides → submit a PR to LibreSign/libresign, not this publisher.
  • Explain the dashboard's latest-report, explorer, history, and preview caveats without implying that high coverage automatically means high quality.
  • Include a concise path for businesses to report real-world failures and sponsor quality work.
  • Move detailed data interpretation to docs/understanding-coverage.md and publisher architecture, permissions, retention, and maintenance into docs/maintainers.md.
  • Keep the English-only presentation and leave license information to the repository's existing LICENSE file, without a README license footer.
  • Update the domain regression test so it checks custom-domain instructions in the maintainer guide rather than forcing that infrastructure detail into the public-facing README.

The main README is now 72 lines (from over 200). This PR modifies documentation and one documentation assertion; no runtime, CI workflow, coverage data, or PHP application behavior is changed.

Verification

  • python3 -m unittest discover -s tests -q: 52 tests passed.
  • All three Markdown files rendered successfully with Pandoc.
  • All local relative links resolve; key public destinations (LibreSign repository, contributor guide, good-first-issue label, testing manual, sponsor page, coverage dashboard and archive) were checked.
  • actionlint on the repository's three workflows passed.
  • git diff --check passed.
  • Signed commit with DCO verified through Git Signing MCP.

Accuracy notes

The LibreSign source publishing integration is still tracked in LibreSign/libresign#9387, not yet merged; the new docs explicitly distinguish a Preview snapshot from verified main coverage.

Review

Please review the README's reader journey and quality principles first, then the two linked reference documents. No automatic merge requested.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
@vitormattos
vitormattos merged commit 0e09ac3 into main Nov 8, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant