Skip to content

Restore --delete to the docs sync - #5293

Merged
kcmartin merged 2 commits into
masterfrom
restore-docs-sync-delete
Oct 8, 2026
Merged

kcmartin merged 2 commits into
masterfrom
restore-docs-sync-delete

Conversation

@kcmartin

@kcmartin kcmartin commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Closes the second half of superfly/docs-tracking#350.

#5287 left --delete out of the rsync because the first sync would also have removed 12 pages that docs.json nav entries and 15 redirects still pointed at. Both halves have now landed: superfly/docs#2530 retired the litefs-cloud command pages, superfly/docs#2535 the duplicate root page.

Verified before restoring: generating from current master and comparing against superfly/docs main gives identical page sets, 305 each, and zero changed pages. So this deletes nothing today.

What it prevents: the litefs-cloud commands were removed in #5187 on 8 September and their eleven pages stayed live for four weeks, documenting a CLI that was not in the binary. Without --delete that happens every time a command goes.

One consequence, noted in the comment: nothing hand-written can live in flyctl/cmd now, since the sync will remove it.

Left out of #5287 because the first sync would have removed 12 pages that
docs.json nav and 15 redirects still pointed at. Those have landed:
superfly/docs#2530 retired the litefs-cloud pages and #2535 the duplicate
root page.

Verified before restoring: generating from master and comparing against
superfly/docs main gives identical page sets, 305 each, and zero changed
pages. So --delete removes nothing today, and from now on a command
removed from flyctl stops being documented.
Neither script uses set -e and out/ is cleared before generating, so a
failed generator leaves out/ empty and the rsync, now with --delete, would
remove every page. The review requirement would catch the resulting PR,
but the script should not rely on that.

A floor rather than set -e: set -e would abort the label-preservation loop,
where [ -n "$label" ] && awk ... returns non-zero for the 270 pages that
carry no sidebarTitle.
@kcmartin

kcmartin commented Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

Added a floor check before the rsync.

Neither this script nor publish_docs.sh uses set -e, and out/ is cleared before the generator runs. So a generator that fails leaves out/ empty, and the rsync with --delete would propagate that and remove every page. It now refuses below 100 files; there are 305 today.

Used a floor rather than set -e because set -e would abort the label-preservation loop: [ -n "$label" ] && awk ... returns non-zero for the 270 pages that carry no sidebarTitle.

Worth noting the interaction: --delete is safe partly because the generated PR now waits for a person, so a 305-deletion PR would never be merged. If we go back to auto-merge, this floor check is the only thing standing between a failed build and an empty command reference.

@kcmartin
kcmartin requested a review from dangra October 6, 2026 18:38
@kcmartin
kcmartin merged commit a1cf49a into master Oct 8, 2026
23 checks passed
@kcmartin
kcmartin deleted the restore-docs-sync-delete branch October 8, 2026 17:29
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.

2 participants