Drop DOC.md in favor of pkg.go.dev - #180
Merged
Merged
Conversation
DOC.md embeds source-line links for every symbol, so any unrelated code change shifts line numbers across large parts of the file -- this made it conflict on nearly every concurrent pull request (the root cause behind the repeated merge-conflict cleanups over the last several PRs). pkg.go.dev already generates the same API reference live from source, with stable per-symbol anchors that don't depend on line numbers, and no regeneration step. So instead of working around the conflict (e.g. custom templates to drop the source links), drop the committed file entirely: - Removes DOC.md, locales/DOC.md, .gomarkdoc.yml, and the "docs" taskfile task. - Rewrites all 50 DOC.md links in README.md to the pkg.go.dev equivalent, and fixes a few anchor inconsistencies that were GitHub-markdown-slug artifacts rather than real conventions (func-maxlen -> MaxLen, func-required -> Required, func-makeregexpchecker -> MakeRegexpChecker, func-istime -> IsTime, ISLte -> IsLte). - Swaps the GoDoc badge for the pkg.go.dev badge; godoc.org has been retired for a while, so that badge was likely already dead. Trade-off: pkg.go.dev serves the latest tagged version, so a link to a symbol not yet in a release won't resolve until the next tag is cut. Given this project's release cadence, that's a better trade than a committed file that conflicts on every other PR. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H9bQZz1DAxYpsfyKbn3Adk
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #180 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 49 49
Lines 752 752
=========================================
Hits 752 752 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Merged
cinar
added a commit
that referenced
this pull request
Sep 5, 2026
## Summary Purely structural/visual — no content or link changes beyond what's described below, layered on top of #180's DOC.md/pkg.go.dev migration (rebased on current `main`, no conflicts). - **Normalized heading levels.** Most major sections (`Checkers Provided`, `Custom Checkers and Normalizers`, `Framework Integration`, etc.) were `#`, the same level as the page title (`# Checker`) itself, while a couple (`Usage`, `Normalizers and Checkers`) were correctly `##`. This bumps the inconsistent ones to `##` (and `Gin`/`Echo` under `Framework Integration` to `###` to stay nested one level down), so the page has one real heading hierarchy — which also fixes GitHub's auto-generated outline sidebar, previously a flat list of same-weight entries. - **Added a table of contents** — the doc is 400+ lines across ~13 major sections with no way to jump around it. - **Added a short feature-highlight bullet list** right under the opening paragraph (zero dependencies, struct tags, checkers+normalizers together, cross-field/conditional rules, 23 locales, framework adapters) — a scannable value-prop up front, ahead of the existing two-paragraph prose intro. ## Test plan - Docs-only change; `go build`/`go test -cover ./...` unaffected (100% coverage maintained, confirmed). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
cinar
added a commit
that referenced
this pull request
Sep 5, 2026
## Problem Every PR added its own bullet to `CHANGELOG.md`'s `## [Unreleased]` section, always inserting at (or near) the same spot. With PRs landing close together, that made this file a near-guaranteed merge conflict on every concurrent pull request — the exact problem `DOC.md` caused before #180 dropped it in favor of pkg.go.dev. This wasn't theoretical: it's what just happened resolving conflicts on #219–#222. Each conflict resolution round immediately conflicted again as the next PR merged, because every remaining branch's `### Fixed` entry inserted into the same place. ## Fix - Freeze the current `## [Unreleased]` section as a one-time snapshot (documenting the six P0 bugfixes plus the earlier accumulated Added/Changed/Removed entries) and add a note explaining the new policy at the top of the file. - Going forward, unreleased changes are covered by [GitHub Releases](https://github.com/cinar/checker/releases), whose notes are generated automatically from merged pull requests — no file to conflict on. `CHANGELOG.md` only gains a new entry when a version is actually tagged, added by hand from that release's generated notes (a maintainer decision, not a per-PR one). - Updated `CLAUDE.md`'s conventions section: PRs no longer touch `CHANGELOG.md`. No code changes; docs/process only. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01FLdVmP5daHiknrTW4Geh2i Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
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.
Summary
DOC.mdembeds source-line links for every symbol, so any unrelated code change shifts line numbers across large parts of the file — this is the root cause behind the repeated merge-conflict cleanups over the last several PRs. Rather than work around it (custom gomarkdoc templates to drop source links, or a bot that regenerates it), this drops the committed file entirely in favor of pkg.go.dev, which already serves the same API reference live from source with stable, line-number-independent anchors and zero regeneration step.DOC.md,locales/DOC.md,.gomarkdoc.yml, and thedocstaskfile task.DOC.md#...links inREADME.mdto thepkg.go.devequivalent, and fixes a few anchor inconsistencies that were GitHub-markdown-heading-slug artifacts rather than real conventions:func-maxlen→MaxLen,func-minlen→MinLen,func-required→Required,func-makeregexpchecker→MakeRegexpChecker,func-istime→IsTime,ISLte→IsLte.pkg.go.devbadge —godoc.orghas been retired for a while, so that badge was likely already dead.CHANGELOG.mdentry.Trade-off: pkg.go.dev serves the latest tagged version, so a link to a symbol merged but not yet released won't resolve until the next tag is cut (versus
DOC.md, which reflectedmain). Given the release cadence here, that's a better trade than a file that conflicts on nearly every concurrent PR.Test plan
go build/go test -cover ./...— 100% coverage maintained (docs-only change, no behavior touched)go vet,gosec,reviveall clean🤖 Generated with Claude Code
https://claude.ai/code/session_01H9bQZz1DAxYpsfyKbn3Adk