Skip to content

feat: summarize documentation changes in the daily refresh release - #115

Merged
ChiragAgg5k merged 2 commits into
mainfrom
feat/docs-refresh-release-notes
Sep 3, 2026
Merged

feat: summarize documentation changes in the daily refresh release#115
ChiragAgg5k merged 2 commits into
mainfrom
feat/docs-refresh-release-notes

Conversation

@ChiragAgg5k

Copy link
Copy Markdown
Member

Why

The daily docs refresh released with a fixed one-line note and gave no indication of what changed, and a quiet run left no trace of why it stopped. With #114 making the artifact deterministic, the build now knows exactly which pages were added, updated, or removed, so the release can say so.

What

  • scripts/build_docs_index.py writes its JSON report to DOCS_REPORT_FILE in the workflow, and refuses to build when fewer than DOCS_MIN_PAGES (default 400) pages come back, so a broken site or export cannot ship a gutted index.
  • New scripts/docs_release_notes.py renders that report into Markdown: page and chunk counts, then Added, Updated, and Removed sections linking each page on appwrite.io.
  • update-docs-index.yml uses the rendered notes as the release body and the commit body, and writes them to the job summary. When the artifact is unchanged the summary says "No changes since the last refresh. Release skipped." and the job exits before committing.

What it produces

Release notes and job summary for a day with changes:

Refresh the embedded Appwrite documentation index.

588 pages, 5870 chunks (24 embedded, 5846 reused).

### Added (2)

- [Passkeys](https://appwrite.io/docs/products/auth/passkeys)
- [docs/products/sites/redirects](https://appwrite.io/docs/products/sites/redirects)

### Updated (1)

- [MySQL](https://appwrite.io/docs/products/databases/mysql)

### Removed (1)

- [WAF](https://appwrite.io/docs/products/network/waf)

Job summary on a quiet day (no commit, no release, no deploy):

## Documentation index

No changes since the last refresh. Release skipped.

Guard output when the site is broken (job fails, artifact untouched):

Only 586 documentation pages fetched (minimum 100000); refusing to build a gutted index

Verification

  • Notes script run on a synthetic report with all three change kinds and on today's real quiet-day report; output above.
  • Guard exercised with DOCS_MIN_PAGES=100000: exit 1, no artifact written.
  • Workflow passes actionlint.
  • ruff, black, pyright, unit tests clean.

Render the build report into release notes listing the added, updated, and
removed pages with links, use them for the release body, the commit body, and
the job summary, and say explicitly when a run is skipped because nothing
changed. Abort the build when the site returns far fewer pages than expected so
a broken export cannot ship a gutted index.
@greptile-apps

greptile-apps Bot commented Sep 3, 2026

Copy link
Copy Markdown

Greptile Summary

The PR adds documentation-refresh reporting, release-note generation, and a minimum-page safeguard.

  • Writes the index build report to a workflow-provided file.
  • Produces page and chunk summaries for commits, releases, and job summaries.
  • Skips release work when the generated index is unchanged.
  • Rejects refreshes that fetch fewer than the configured minimum number of pages.

Confidence Score: 5/5

The PR appears safe to merge with no blocking failure remaining.

No blocking failure remains.

Important Files Changed

Filename Overview
.github/workflows/update-docs-index.yml Connects the build report to generated commit and release notes, records job summaries, and preserves downstream release dispatch.
scripts/build_docs_index.py Adds a configurable minimum-page threshold before generating or replacing the documentation index.
scripts/docs_release_notes.py Introduces deterministic Markdown rendering for documentation change reports.
docs/documentation-search.md Documents the page-count guard and daily documentation-refresh lifecycle.

Reviews (2): Last reviewed commit: "fix: escape Markdown in release-note pag..." | Re-trigger Greptile

Comment thread scripts/docs_release_notes.py Outdated
Titles come from fetched front matter, so neutralize link-breaking characters
and percent-encode the path before building the link.
@ChiragAgg5k
ChiragAgg5k merged commit 2a3cc59 into main Sep 3, 2026
5 checks passed
@ChiragAgg5k
ChiragAgg5k deleted the feat/docs-refresh-release-notes branch September 3, 2026 14:54
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