Apply every rename when updating links between renamed files

[eastagiletracker]

This PR proposes a one-line fix to .config/update_rename_links.py so that links between renamed pages are rewritten for every rename in a pull request instead of only the last one. We include this PR work along with a full history of your repo at https://eastagiletracker.com/projects/282. You can sign in with your GitHub ID to claim ownership of the project.

What goes wrong

update_links_between_renamed_files() seeds new_content from the file it is fixing and then loops over the renames, but each pass recomputes the replacement from the pristine content rather than from the running result:

new_content = content
for old_link, new_link in renames:
    old_relative, new_relative = calculate_relative_paths(old_link, new_link, old)
    new_content = replace_link(content, old_relative, new_relative)  # content, not new_content

Every pass discards the previous one, so at most one rename is ever reflected in a given page — whichever happens to come last. When a pull request moves two or more pages that link to each other, the pages whose target is not last keep links to paths that no longer exist. Because .github/workflows/manage-renames.yml runs this script on every pull request and auto-commits the result, those stale links land on the contributor's branch, and mkdocs build --strict then rejects the branch the script was supposed to repair.

The neighbouring helper update_renamed_file_links() already accumulates correctly with new_content = new_content.replace(...), which is what suggested this is a slip rather than a deliberate difference.

Reproducing on master

At f16dfc1 on master, move two pages that link to each other into different subdirectories — the shape of a section reorganisation:

$ git checkout -b repro
$ mkdir -p about-this-guidebook/contributing about-this-guidebook/governance
$ git mv about-this-guidebook/editing-the-guidebook.md about-this-guidebook/contributing/editing-the-guidebook.md
$ git mv about-this-guidebook/guidebook-governance.md about-this-guidebook/governance/guidebook-governance.md
$ git commit -m "move two mutually linking pages"
$ python3 .config/update_rename_links.py master repro
...
Updated links between renamed files in about-this-guidebook/contributing/editing-the-guidebook.md

Only one of the two pages is rewritten. The other still carries the link it had before the move, now pointing at nothing:

$ grep -n "](editing-the-guidebook.md)" about-this-guidebook/governance/guidebook-governance.md
7:Any team member with a GitHub account can make [pull requests](editing-the-guidebook.md) to change any part of the guidebook.

and the strict site build that .config/mkdocs/mkdocs.sh runs fails on exactly that link:

$ mkdocs build --strict --config-file .config/mkdocs.yml
WARNING -  Doc file 'about-this-guidebook/governance/guidebook-governance.md' contains a link 'editing-the-guidebook.md', but the target 'about-this-guidebook/governance/editing-the-guidebook.md' is not found among documentation files.
Aborted with 1 warnings in strict mode!

The change, and how it was checked

The fix is to build on the running result, so each rename is applied on top of the last:

new_content = replace_link(new_content, old_relative, new_relative)

Since the repo has no test harness for these scripts, each check below is a command you can replay on this branch in a minute:

• Baseline. mkdocs build --strict on a clean master at f16dfc1 completes with no warnings, so anything new below is attributable to the change.
• The reproduction above, on this branch. Both pages are now rewritten (../governance/guidebook-governance.md and ../contributing/editing-the-guidebook.md), and the same strict build completes with no warnings.
• A page linking to two other renamed pages. Moving incident-response-plan.md, incident-response-checklist.md and incidents.md into a new incidents/ directory: on master the plan page keeps both of its links stale and is not even reported as updated; on this branch both are rewritten and resolve to files that exist.
• Repeat runs. Running the script a second time over an already-updated tree changes no markdown, so the workflow's auto-commit step stays a no-op.
• Single renames are untouched. For a one-file rename, the markdown produced on this branch is byte-identical to master's, and the script prints the same output — the change only affects the second and later renames, which are currently dropped.

Nothing else in the file is touched, and no page content is changed by this PR.

How this was managed

This work was tracked on a board imported from this repository's own issues and pull requests — 1776 stories and 13 labels — with this fix as its own story on the board at https://eastagiletracker.com/projects/282.

If you'd rather not receive contributions like this, reply no-more-prs on this pull request and we won't open any further ones on your repositories.

---

Lawrence W. Sinclair
CEO / East Agile
linkedin.com/in/lwsinclair/
eastagile.com