Skip to content

docs: rework the README to the org layout and fix two false statements - #50

Merged
shenxianpeng merged 1 commit into
mainfrom
chore/align-readme-with-org-standard
Oct 1, 2026
Merged

shenxianpeng merged 1 commit into
mainfrom
chore/align-readme-with-org-standard

Conversation

@shenxianpeng

Copy link
Copy Markdown
Member

Part of aligning the READMEs across the org (same layout as cpp-linter/cpp-linter-hooks#289).

What changed

Header

  • Badges: ci (build.yml) and part of cpp-linter.
  • Removed the <div>, the badges inside the H1, the Lint badge and the emoji hub badge.
  • There is no release badge: asdf plugin add clones main, so nobody installs a release tag.
  • Sections were H1 headings; they are H2 now.

False today, now fixed

  • asdf set comment: it said the command writes ~/.tool-versions. Since asdf 0.16 it writes ./.tool-versions; -u writes the home file. The Quick start now says it needs asdf 0.16 or later.
  • macOS de-quarantine: the plugin never offers it. lib/utils.bash checks for macosx, but the platform is macos, so ASDF_CLANG_TOOLS_MACOS_DEQUARANTINE does nothing. curl does not set the quarantine attribute, and the binaries ran with no Gatekeeper prompt. The variable is removed from the README, which now says this.

Clarified, each tested

  • The tools are not in asdf's plugin list, so the URL is required.
  • The plugin name must be the tool name: with clang-tools as the name, install fails.
  • Versions are LLVM majors: asdf install clang-format 21.1.0 fails.
  • The bare clang-format example read stdin and waited; it now runs clang-format --version.
  • GITHUB_TOKEN is now listed: the scripts send it with the release API request.

Removed

  • The Windows line: asdf has no Windows release, and plugin CI has no Windows runner.
  • The "make sure you trust that repository" line and duplicates.

Checked

  • The Quick start ran as written with asdf 0.20.2 (latest) in a throwaway install. clang-format --version printed the LLVM 23 build.
  • All links return 200.
  • The repo's pre-commit hooks pass.

Not in this PR

  • The dead de-quarantine block in lib/utils.bash and its env var in build.yml.
  • The asdf plugin test clang-tools ... commands in CONTRIBUTING.md, which fail.

Follow the layout the other cpp-linter READMEs move to: name, two
badges, one sentence, a link line, then Quick start, Usage, Supported
versions, Platforms, Dependencies, Environment variables, Contributing
and License. Sections were H1 headings; they are H2 now.

`asdf set` writes .tool-versions in the current directory, not
~/.tool-versions (that needs -u). The plugin never offers to remove the
macOS quarantine attribute: the check compares against "macosx" while
the platform is "macos", and curl does not set the attribute anyway, so
drop ASDF_CLANG_TOOLS_MACOS_DEQUARANTINE from the README.

Also say that versions are LLVM majors, that the plugin name must be the
tool name, and that GITHUB_TOKEN raises the API rate limit.
@shenxianpeng shenxianpeng added the documentation Improvements or additions to documentation label Oct 1, 2026
@shenxianpeng
shenxianpeng merged commit 5c5e275 into main Oct 1, 2026
3 checks passed
@shenxianpeng
shenxianpeng deleted the chore/align-readme-with-org-standard branch October 1, 2026 07:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant