docs: translate the first four ADRs to english - #14
Merged
Conversation
ADR-0006 made English the language of the ADRs, but only from that point on. Four Portuguese documents were left behind, and they are the ones a reader opens first: monorepo, pgvector, the Python/TypeScript boundary, deterministic generation. A decision record nobody in the audience can read is not a record. Filenames follow the content, so a reader browsing docs/adr/ does not meet a Portuguese filename holding an English document. Every reference was updated. Two fixes found on the way. The rules document linked to a threat model that does not exist yet, which was a 404 rather than a note. And there is now a test that walks every Markdown file in the repository and asserts its relative links resolve — it lives in the API suite because that is the only runner CI has, and a separate workflow would be another required check to keep green. ADR-0002 also gained the version drift discovered when the stack first came up: the container image ships pgvector 0.8.6 while the managed instance is on 0.8.2.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Point 4, closing the internationalisation sequence started in #12.
Four, not three
ADR-0006 made English the language of decision records from that point forward,
which left four Portuguese documents behind, not three — 0004 predates the
rule by a few hours. They are also the ones a reader opens first.
Filenames follow the content. Meeting
0003-python-fastapi-no-core-de-ia-e-next-como-bff.mdwhile browsing adirectory of English documents is exactly the half-migrated look ADR-0006 argues
against. All references updated.
Two things found on the way
A broken link.
docs/02-regras-de-negocio.mdpointed at05-threat-model.md, which does not exist yet. It was marked "(a escrever)" inthe text, but it was still a 404 for anyone who clicked it.
So there is now a test for that.
test_docs_links.pywalks every Markdownfile in the repository and asserts every relative link resolves. It lives in the
API suite deliberately: that is the only runner CI has, so it rides the existing
testcheck instead of adding another required one. It also asserts the globfound documents at all — a glob that silently matches nothing makes every other
assertion pass.
In a repository where the documentation is part of what is being judged, a dead
link is small and reads as carelessness.
One content change, not just translation
ADR-0002 gained a consequence discovered when the stack first came up: the
container image ships pgvector 0.8.6 while the managed instance is on
0.8.2. A new index feature has to be checked against production before it is
used.
What stays in Portuguese
The design documents — plan, domain, business rules. They are the ones almost
nobody opens, the glossary maps both vocabularies, and the two days are better
spent on the game.