[Doc]: Create developer documentation

[whg517]

To effectively communicate the project's development and release processes to collaborators, particularly AI assistants, it is necessary to create comprehensive documentation that supports developers in learning, understanding, and actively participating in the development workflow. The documentation should address the following key areas:

• Instructions for setting up the local development environment.
• An overview of project modules and underlying design principles.
• A step-by-step guide on implementing and contributing a new feature from a practical use case perspective.
• Procedures for submitting locally developed features to the organization’s repository, including established collaboration norms and coding standards.
• A detailed description of the version release process.

[whg517]

duplicate #165

[whg517]

Triaged bullet by bullet against the repo as it stands. Two of the five are substantially answered — by work that landed after this issue was filed — and three are genuinely open. One of them got worse two days ago; #626 fixes that part.

Where each bullet stands

bullet	status
(b) modules overview + design principles	done — docs/architecture.md (1395 lines: design philosophy, layered architecture, one subsection per module, design patterns), docs/security.md, AGENTS.md §1–§16, and 7 more per-package AGENTS.md. All added 2026-03-03 in the framework redesign (#441), four months after this issue.
(d) collaboration norms + coding standards	mostly — the org's published guide covers the norms, and the standard is now enforced mechanically by CI (golangci-lint, verify-generate, the test matrix) rather than described. What is missing is that operator-go contains zero links to that guide.
(a) local development environment	open
(c) step-by-step guide to contributing a feature	open
(e) release process	open, and it regressed

On (b): "AGENTS.md is long" is not coverage of (a) — it tells an agent how the framework works, not a newcomer how to get a working environment. Those are different documents.

(e) regressed two days ago, and #626 fixes the dishonest half

#621 added to AGENTS.md:

The entries under a version heading are generated at release time from the commit history … see the release procedure for tagging and version bumps.

Neither exists. .github/workflows/ holds only lint.yml and test.yml; there is no goreleaser, no release-please, no release workflow; hack/ holds only the boilerplate header. The observed practice for v0.12.6 was a manual tag plus a hand-written CHANGELOG PR — and the two records already disagree (CHANGELOG.md dates it 2025-12-01, the GitHub release was published 2026-01-18).

That made it an aspirational statement inside an AGENTS.md, which its own scope rule forbids ("anything aspirational belongs in docs/architecture.md and must be explicitly labelled as such"). It is also the only dangling see the … prose reference in the tree.

#626 corrects it to say what actually happens — a maintainer writes the section by hand from the commit history — and points here for the undocumented tagging and version bump. Writing the release doc itself is still open; that is the remaining half of (e).

Two collateral defects found while checking coverage

Both would degrade the fix for this issue, so they are worth their own tickets:

1. The md-lint CI job checks nothing. .github/workflows/lint.yml globs README.*.md, which matches no file in the repo (README.md and README_zh-CN.md both fail that pattern). So a documentation PR — including any fix for this issue — is linted by nothing today. Widening the glob to *.md/docs/**/pkg/** surfaces 759 pre-existing violations (412 in docs/architecture.md, 130 in docs/DOC_CHANGELOG.md, 103 in AGENTS.md; mostly MD013 line-length, MD007 list indent, MD060 table pipes). Whether to relax .markdownlint.yml or fix them is a house-style decision, so feat(authentication): make "exactly one provider" enforceable, and readable the same way everywhere #626 deliberately does not touch it.

2. .pre-commit-config.yaml pins a golangci-lint that cannot be built under the repo's Go 1.25.3, while the org PR checklist tells every contributor to run pre-commit.

Suggested rescope

Keep this open for (a), (c) and (e), and treat it as three small documents rather than one large one — a CONTRIBUTING.md that gets a newcomer to a green make test, a walkthrough that follows one real feature through the gates, and a release runbook. The project has just spent effort removing duplicated prose (#621), so each should point at AGENTS.md/docs/architecture.md rather than restate them, and (d) should be satisfied by a link to the org guide rather than a local copy.

The earlier comment calls this a duplicate of #165, but #165 was closed as completed 14 seconds after that comment — housekeeping, not delivered work — so this is the surviving ticket.

[whg517]

Deferred — not being worked on. Marked wontfix as a do-not-pick-up signal rather than a rejection; the bullet-by-bullet triage in the comment above stands.

Two things from that triage are worth flagging as still-live, because they are independent of the documentation work itself and will quietly degrade whoever does eventually pick this up:

1. The md-lint CI job checks nothing — .github/workflows/lint.yml globs README.*.md, which matches no file in the repo. Any documentation PR, including a fix for this issue, is linted by nothing. Widening the glob surfaces 759 pre-existing violations, so it needs a house-style decision (relax .markdownlint.yml vs fix them) rather than a drive-by change.
2. AGENTS.md still points at a release procedure that does not exist, and still asserts a release-time changelog generator that does not exist (added in docs: generate the changelog at release time, not per PR #621). That is an aspirational statement inside an AGENTS.md, which its own scope rule forbids. The one-paragraph correction was in PR feat(authentication): make "exactly one provider" enforceable, and readable the same way everywhere #626, which is now closed — branch docs/backlog-triage still has it, and it has no prerequisite, so it can be re-landed on its own at any time.

Bullet (b) — modules overview and design principles — is genuinely done (delivered by #441, four months after this issue was filed). If this is ever rescoped, it should cover only (a), (c) and (e).