Uber Go Style Guide: the published file is generated, and the tags stopped in 2023

style.md is built from src, so editing the published file is a mistake

The repository holds two things: the guide itself, style.md, and a src directory that the guide is built from. The Makefile makes the relationship explicit, with the default goal set to style.md and the rule that regenerates it depending on both the tool and a wildcard over the contents of src. Two inputs are named in the arguments, a preface file and a summary file, so the table of contents and the front matter of the published document are themselves source files. The consequence is that a contributor who opens style.md and fixes a sentence has changed a build artifact, and the next person to run the default target overwrites it. That is not a matter of taste in this repository, it is enforced: a separate lint target exists for the purpose.

go install go.abhg.dev/stitchmd@latest

A lint target exists to fail the build when style.md drifts

The lint target runs the generator in diff mode against the same arguments used to produce the file, captures the output, and if that output is not empty it prints style.md is out of date: followed by the diff itself and then fails. The check is therefore self comparing. It does not ask whether the prose is good, and it does not lint Go, because there is no Go here. It asks one mechanical question, whether the checked in file matches what the sources would produce right now. For a team running this in its own fork, the practical value is that you cannot quietly let the published guide and the source directory disagree, and the practical cost is that every change needs the tool installed and run locally before it can be proposed, otherwise the same check fires in continuous integration.

The generator is installed at a floating version, not a pinned one

Look at how the tool is obtained and you find a floating reference rather than a fixed one. The Makefile sets GOBIN so that go install places the binary inside a bin directory inside the repository itself, which keeps it out of your global path, and then the rule that builds it runs go install against go.abhg.dev/stitchmd at the latest tag. The Makefile also declares SHELL as /bin/bash, so the recipe logic that compares the diff is bash rather than the default shell. The consequence of the floating version is that the generator is not part of the project's reproducibility story. A new stitchmd release can change how the file is assembled, which means a build that passed lint on your machine last month can fail on someone else's this month with no change to src at all, and there is no version file in the tree that pins what was used.

The same generator arguments are duplicated into the workflow file

The arguments that build the document are not defined in one place. The Makefile holds them, output path, preface path and summary path, and directly above that line there is a comment instructing that the options be kept in sync with the workflow file under .github. That is an admission in the build system that two copies of the same configuration exist, and it defines the failure mode precisely. Rename the output file, move the preface, or change the source directory in the Makefile and the copy used by continuous integration still asks for the old layout, so the diff comes back non empty and the build fails for a reason that has nothing to do with your change. A contributor working in this repository has to edit both, and the comment is the only warning that the second copy exists, since the README explains nothing about the build at all.

The newest release tag is from 2023 while the branch is still moving

Look at the tags rather than the branch and the picture changes. The recent releases are named after dates rather than versions, 2023-05-09, then 2023-04-13, then 2022-10-18, so the most recent published release is the one from 2023-05-09. The default branch is master, and its last push is dated 2026-04-15, which is well after that tag. Nothing in the repository claims the releases are maintained on a schedule, and the tag format being a bare date makes it obvious at a glance that these are snapshots of a moment rather than versioned artifacts. The consequence for a reader is that anything pinning a release gets a 2023 snapshot of the guide, and anyone who wants the current conventions has to read the branch, where the text may have changed in ways the tag does not reflect.

Seventeen translations live in their own repositories, untracked by this one

The community translation list is the longest part of the README, and it points outward to seventeen separate repositories. They cover Chinese, Traditional Chinese, Korean, Japanese, Spanish, Thai, Portuguese, Portuguese Brazil, Polish, Russian, French, Turkish, Ukrainian, Persian, Vietnamese, Arabic and Indonesian, each maintained under its own author. The contribution instruction is correspondingly narrow, asking anyone with a translation to open a pull request that adds a link to this list, which is a link addition and not a review of the translation. The consequence follows from where the text lives. A rule that changes in the English original does not propagate to any of them, no CI job in this repository can tell whether a translation is current, and the list gives no indication of which language is closest to the source. Picking a translation is therefore a decision you make without evidence and verify yourself.

A Go linter config sits in a repository that contains no Go code

The repository root carries a .golangci.yml alongside the Makefile, the style guide, the source directory, a changelog, a code of conduct, a contributing file and the license. The declared primary language of the repository is a Makefile, and the only Go invocation anywhere in the build is the single install line for the generator. The README does not explain what it is for or which workflow consumes it. The reasonable reading is that it applies to tooling that lives alongside the guide rather than to the guide itself, but nothing on the page confirms that.

Editorial conclusion

Adopt the Uber Go Style Guide as a document you argue from, not as a dependency you install, and treat a tagged release as a historical snapshot rather than the current text, since the newest tag is from 2023-05-09 and master has moved since. If you plan to contribute, edit the files under src and regenerate, because a hand edit to style.md is exactly what the lint target is built to catch. Before you standardize a team on it, read the guide itself rather than the README, since the README scopes the project in a single sentence and says nothing about which Go version or which Uber code the conventions come from, and prefer a community translation only if you can check it against the English original yourself, because nothing in the list tracks how current each one is.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. uber-go/guide on GitHub