Skip to content

docs: stop restating what go-code-standards specifies - #76

Closed
retr0h wants to merge 1 commit into
mainfrom
docs/stop-restating-shared-conventions
Closed

docs: stop restating what go-code-standards specifies#76
retr0h wants to merge 1 commit into
mainfrom
docs/stop-restating-shared-conventions

Conversation

@retr0h

@retr0h retr0h commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

CONTRIBUTING.md pointed at the go-code-standards capability and then restated it, closing with "Where the two disagree, the specification wins." That sentence acknowledges the duplication rather than removing it — and the two copies drift independently, which is what the repo-standards requirement Each fact is stated once forbids:

A fact SHALL be stated in exactly one file — the one that owns it — and every other file that needs it SHALL point there rather than restating it.

Removed

The multi-line signature rule, test package layout, suite naming, table-driven cases, and the error-wrapping / early-return / import-order baseline. All are requirements in go-code-standards.

Kept

The golangci-lint set and the note that tests drive a real HTTP server via httptest.Server — neither is in the capability.

Also fixes an internal duplication

## Code standards and ## Testing each described test package layout, suite naming, and table-driven cases. Same facts, two places, one file.

This matches the pattern osapi's new CONTRIBUTING.md uses (osapi-io/osapi#450), which points without restating.

just test passes, coverage still 100%.

Closes the osapi-orchestrator half of specify-go-code-standards task 3.6.

🤖 Generated with Claude Code

CONTRIBUTING.md pointed at the go-code-standards capability and then
restated it, saying the specification wins where the two disagree. That
acknowledges the duplication rather than removing it, and the two drift
independently.

The restatement was doubled internally as well: Code standards and
Testing both described test package layout, suite naming, and
table-driven cases.

Removed: the multi-line signature rule, test package layout, suite
naming, table-driven cases, and the error-wrapping and import-order
baseline. Kept the linter set and the note that tests drive a real HTTP
server.

Satisfies the repo-standards requirement that a fact is stated in
exactly one file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Thank you for contributing to this project! 😊🕹️

@codecov

codecov Bot commented Aug 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Impacted file tree graph

@@            Coverage Diff            @@
##              main       #76   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           14        14           
  Lines         3217      3217           
=========================================
  Hits          3217      3217           

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 29e2be3...d3296d5. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@retr0h

retr0h commented Aug 16, 2026

Copy link
Copy Markdown
Contributor Author

Holding this as a draft.

Two things surfaced after it was opened:

  1. go-code-standards was not in the corpus. It existed only inside the unarchived change, so the pointer this PR leaves behind resolved to nothing. feat: put go-code-standards in the corpus specs#88 fixes that and should merge first.

  2. The direction is under review. The capability states Go formatting conventions — multi-line signatures, import grouping, error wrapping — as spec requirements. Those are not externally observable behavior, which is what config.yaml says a requirement should describe. A proposal to rescope the capability is being written; this PR waits on its outcome rather than converting a third repository in a direction that may reverse.

gohai already merged the equivalent change (osapi-io/gohai#163), so it is the repository to watch if the rescope lands.

@retr0h

retr0h commented Aug 16, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #77, which standardizes CONTRIBUTING.md instead of emptying it.

This PR removed the shared conventions and left a pointer to the go-code-standards capability. Review established that the opposite is wanted: every repository states its conventions in full, with the five files structurally identical. That is what osapi-io/specs#89 and osapi-io/specs#90 agreed, and what #77 applies.

@retr0h retr0h closed this Aug 16, 2026
retr0h added a commit that referenced this pull request Aug 16, 2026
The five Go repositories stated the same conventions five different
ways. Here they were split across Code standards and Testing, which each
described test package layout, suite naming, and table-driven cases --
the same facts twice in one file.

Applies the section order repo-standards now fixes: Setup, Project
structure, Code style, Code standards, Testing, then the operation
walkthrough. Package Structure folds into Project structure, and the
Title Case headings become sentence case.

The linter list is gone. It named goimports as a linter and omitted
unused, while .golangci.yml has enabled unused all along and configures
goimports as a formatter.

Supersedes #76, which removed these conventions rather than
standardizing them.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant