Maniphest T401349

docs: 404 errors in Codex documentation
Closed, ResolvedPublic1 Estimated Story Points
Actions

Assigned To

Authored By

	Waddie96
	Aug 6 2025, 7:28 PM

Project Tags

Referenced Files

None

Subscribers

Description

Description

For minor typing errors and link correction. I don't know how to do a commit yet.

Changes

https://doc.wikimedia.org/codex/main/using-codex/guiding-principles.html links to https://design.wikimedia.org/style-guide/design-principles_accessibility.html which is a 404 error.

https://doc.wikimedia.org/codex/main/using-codex/adrs/overview.html links to https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md which is a 404 error. Should be https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md

~[ ] write a ticket to write tests to automatically test for broken links in Codex~

Details

Related Changes in Gerrit:

	Subject	Author	Repo	Branch	Lines +/-
	Update Codex from v2.3.1 to v2.3.2	VolkerE	mediawiki/core	master	+242 -162
	Fix a couple dead links in the Codex documentation.	Bvibber	design/codex	main	+4 -2

Customize query in gerrit

Related Objects

Mentioned In: T404468: Codex test suite should check for 404 errors on documentation links
Mentioned Here: T404468: Codex test suite should check for 404 errors on documentation links

Event Timeline

Waddie96 created this task.Aug 6 2025, 7:28 PM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptAug 6 2025, 7:28 PM

Waddie96 updated the task description. (Show Details)Aug 7 2025, 5:04 AM

Aklapper renamed this task from Corrections of minor errors and deadlinks to 404 errors in Codex documentation.Aug 7 2025, 2:02 PM

Aklapper updated the task description. (Show Details)

Volker_E renamed this task from 404 errors in Codex documentation to docs: 404 errors in Codex documentation.Aug 8 2025, 3:43 AM

Catrope triaged this task as High priority.Aug 18 2025, 6:41 PM

Catrope moved this task from Backlog to Ready for Design/Dev on the Codex board.

Catrope added a project: Reader Growth Team.Aug 25 2025, 8:30 PM

Catrope moved this task from Incoming/Inbox to Needs Refinement on the Reader Growth Team board.

Edtadros subscribed.Sep 2 2025, 1:44 PM

HSwan-WMF updated the task description. (Show Details)Sep 10 2025, 4:41 PM

HSwan-WMF set the point value for this task to 1.

Jdlrobson-WMF moved this task from Needs Refinement to Ready on the Reader Growth Team board.Sep 10 2025, 4:44 PM

Jdlrobson-WMF added a project: Readers Essential Work.Sep 10 2025, 8:51 PM

Jdlrobson-WMF moved this task from For triage to Tracking on the Readers Essential Work board.

Jdlrobson-WMF edited projects, added: Readers Essential Work (Codex); removed: Readers Essential Work.

HSwan-WMF moved this task from Ready to Sprint 5 on the Reader Growth Team board.Sep 11 2025, 4:18 PM

HSwan-WMF edited projects, added: Reader Growth Team (Sprint 5); removed: Reader Growth Team.

bvibber claimed this task.Sep 12 2025, 6:16 PM

bvibber moved this task from Committed to Doing on the Reader Growth Team (Sprint 5) board.

I replaced

https://design.wikimedia.org/style-guide/design-principles_accessibility.html

with

https://doc.wikimedia.org/codex/main/style-guide/accessibility.html

which appears to be the successor document?

and

https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md

with

https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md

(it has moved a directory down as noted in the original post)

And I broke out a task T404468 for adding a link check to the test suite, which would allow us to catch newly failing old links as well as typoes in new additions.

Change #1187879 had a related patch set uploaded (by Bvibber; author: Bvibber):

[design/codex@main] Fix a couple dead links in the Codex documentation.

https://gerrit.wikimedia.org/r/1187879

gerritbot added a project: Patch-For-Review.Sep 12 2025, 6:30 PM

bvibber moved this task from Doing to Code Review on the Reader Growth Team (Sprint 5) board.Sep 12 2025, 6:32 PM

@DTorsani-WMF https://design.wikimedia.org/style-guide/design-principles_accessibility.html is a dead link found in the Codex guiding principles page, and it was replaced with the Codex accessibility style guide. Is this a suitable replacement for that dead link?

Change #1187879 merged by jenkins-bot:

[design/codex@main] Fix a couple dead links in the Codex documentation.

https://gerrit.wikimedia.org/r/1187879

Maintenance_bot removed a project: Patch-For-Review.Sep 12 2025, 9:31 PM

lwatson moved this task from Code Review to Signoff on the Reader Growth Team (Sprint 5) board.Sep 12 2025, 9:38 PM

lwatson moved this task from Ready for Design/Dev to Design Review on the Codex board.Sep 12 2025, 9:43 PM

Hi @Waddie96, thanks for filing the dead links in Codex docs! Regarding your comment in the task description, start with the Gerrit tutorial https://www.mediawiki.org/wiki/Gerrit/Tutorial and the Codex contributing page https://doc.wikimedia.org/codex/latest/contributing/overview.html

I don't know how to do a commit yet.

Thanks!

@lwatson yes, I would say that is a fine replacement. Thank you!

The part about automatically testing for broken links is a good idea but should be spun out into a future task.

Otherwise I consider this resolved, the links work on the main branch of the codex docs and the latest branch (the default) will be updated whenever the next Codex release goes out.

In T401349#11182073, @egardner wrote:

The part about automatically testing for broken links is a good idea but should be spun out into a future task.

I spun that out to T404468, looks like we're good for now! Lemme make sure it's in our backlog.

Change #1191541 had a related patch set uploaded (by VolkerE; author: VolkerE):

[mediawiki/core@master] Update Codex from v2.3.1 to v2.3.2

https://gerrit.wikimedia.org/r/1191541

gerritbot added a project: Patch-For-Review.Sep 26 2025, 12:13 AM

Change #1191541 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v2.3.1 to v2.3.2

https://gerrit.wikimedia.org/r/1191541

Maintenance_bot removed a project: Patch-For-Review.Sep 26 2025, 4:32 PM