◐ Off-By-One · answer catalog

go-docs-gate11-hygiene

2 answer(s)godockergodocker

REPOROOT="$(cd "$(dirname "${BASHSOURCE[0]}")/.." && pwd)"

📦 Source in repository (JSON)

Answer 1

Root cause. v1.0.0 shipped without SUPPORT.md / CODE_OF_CONDUCT.md / .gitattributes because Gate 11 was skipped under the zombie-pause exception; on re-enable, the gate was closed "foreman-direct" (run inline in the release foreman job) with mechanical docs — but the docs were hand-written once with no worker, no generator, and no re-check, so drift and regression were possible. Two stale worker-timeout stashes were also left in the repo. The fix makes the gate unskippable, self-checking, and self-healing.

The fix, delivered as a real repo at ~/go-docs-gate11-hygiene:

  1. Add the three missing files — real, non-stub content:
  2. SUPPORT.md: scope, how to get help, private security channel (<email>), triage SLAs, bug-report template, maintenance status for v1.0.0.
  3. CODE_OF_CONDUCT.md: Contributor Covenant v2.1 with enforcement ladder and <email> contact.

  4. .gitattributes: * text=auto, eol=lf for Go sources/tooling, binary for *.exe/*.test/*.prof/*.so/*.a, vendor/ -text, and linguist-documentation overrides so release docs aren't counted as code.

  5. Foreman-direct mechanical generator — scripts/gen-hygiene-docs.sh (the "no worker" guarantee is structural: it runs inline in the release job, so a worker timeout can never skip it again). It writes all three files with a @generated by scripts/gen-hygiene-docs.sh (foreman-direct). Do not edit by hand. marker and is idempotent:

# scripts/gen-hygiene-docs.sh (excerpt)
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
set -euo pipefail
write_support; write_coc; write_gitattributes   # heredoc templates
  1. Re-enabled Gate 11 — scripts/verify-hygiene.sh. All four checks must pass or the release is blocked:
# 1. presence + non-empty
for f in SUPPORT.md CODE_OF_CONDUCT.md .gitattributes; do
  [ -f "$f" ] && [ -s "$f" ] || fail "missing $f"
done
# 2. required content markers (security contact, covenant, eol/binary rules)
grep -q '<email>' SUPPORT.md        || fail ...
# 3. no drift: snapshot -> regenerate -> byte-compare the 3 managed files
for f in SUPPORT.md CODE_OF_CONDUCT.md .gitattributes; do
  diff -q "$tmp/$f" "$REPO_ROOT/$f" >/dev/null || fail "drift: $f differs from generator output"
done
# 4. drop stale worker-timeout stashes (self-healing on re-enable)
while git stash list | grep -q 'worker-timeout'; do
  idx="$(git stash list | grep 'worker-timeout' | head -1 | cut -d: -f1)"
  git stash drop "$idx" >/dev/null
done

  1. Dropped the 2 stale worker-timeout stashes (done by the gate itself at re-enable; verified gone afterward).

  2. Locked with a Go test suite — hygiene_test.go (9 tests) so any future regression reopens Gate 11 in CI.

Evidence & signatures

All verification ran in the actual repo, not just by inspection:

- **Gate 11 re-enable run** (with the 2 stale `worker-timeout` stashes recreated first):
  ```
  GATE11 ok: present and non-empty: SUPPORT.md / CODE_OF_CONDUCT.md / .gitattributes
  GATE11 ok: required content markers present
  GATE11 ok: committed docs match generator output (no drift)
  GATE11 ok: dropped stale worker-timeout stash(es)
  GATE11 ok: no stale worker-timeout stashes
  GATE 11 CLOSED: release hygiene verified.
  ```
  Stash list went from `stash@{0} worker-timeout: test artifact cleanup` + `stash@{1} worker-timeout: warm build cache` to **empty**; `git status` clean afterwards (idempotency confirmed — regeneration changed nothing).
- **`go vet ./...` clean; `go test -v ./...` → 9/9 PASS**: `TestGate11FilesExistAndNonEmpty`, `TestSupportContent`, `TestCodeOfConductContent`, `TestGitAttributesContent`, `TestLFOnlyInManagedTextFiles` (no CRLF, matching `eol=lf`), `TestGeneratorIdempotentAndDriftFree`, `TestGate11ScriptPasses`, `TestNoStaleWorkerTimeoutStashes`, `TestGateBlocksOnMissingFile`.
- **Edge cases tested:** (a) gate fails hard on a missing file — removing `SUPPORT.md` yields `GATE11 FAIL: missing SUPPORT.md`, exit 1, so re-enable can't be silently skipped again; (b) drift — the gate byte-compares committed docs to generator output, so hand-edited "mechanical" docs fail; (c) idempotency — generator run twice produces identical trees; (d) stale stashes — both dropped and asserted gone; (e) Windows/CRLF exposure — `eol=lf` rules verified against actual file bytes.
{"model": "deepseek-v4-flash", "problem_class": "go-docs-gate11-hygiene", "result": "passed", "tests": 9}

Answer 2

Root cause. v1.0.0 shipped without SUPPORT.md / CODE_OF_CONDUCT.md / .gitattributes because Gate 11 was skipped under the zombie-pause exception; on re-enable, the gate was closed "foreman-direct" (run inline in the release foreman job) with mechanical docs — but the docs were hand-written once with no worker, no generator, and no re-check, so drift and regression were possible. Two stale worker-timeout stashes were also left in the repo. The fix makes the gate unskippable, self-checking, and self-healing.

The fix, delivered as a real repo at ~/go-docs-gate11-hygiene:

  1. Add the three missing files — real, non-stub content:
  2. SUPPORT.md: scope, how to get help, private security channel (<email>), triage SLAs, bug-report template, maintenance status for v1.0.0.
  3. CODE_OF_CONDUCT.md: Contributor Covenant v2.1 with enforcement ladder and <email> contact.

  4. .gitattributes: * text=auto, eol=lf for Go sources/tooling, binary for *.exe/*.test/*.prof/*.so/*.a, vendor/ -text, and linguist-documentation overrides so release docs aren't counted as code.

  5. Foreman-direct mechanical generator — scripts/gen-hygiene-docs.sh (the "no worker" guarantee is structural: it runs inline in the release job, so a worker timeout can never skip it again). It writes all three files with a @generated by scripts/gen-hygiene-docs.sh (foreman-direct). Do not edit by hand. marker and is idempotent:

# scripts/gen-hygiene-docs.sh (excerpt)
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
set -euo pipefail
write_support; write_coc; write_gitattributes   # heredoc templates
  1. Re-enabled Gate 11 — scripts/verify-hygiene.sh. All four checks must pass or the release is blocked:
# 1. presence + non-empty
for f in SUPPORT.md CODE_OF_CONDUCT.md .gitattributes; do
  [ -f "$f" ] && [ -s "$f" ] || fail "missing $f"
done
# 2. required content markers (security contact, covenant, eol/binary rules)
grep -q '<email>' SUPPORT.md        || fail ...
# 3. no drift: snapshot -> regenerate -> byte-compare the 3 managed files
for f in SUPPORT.md CODE_OF_CONDUCT.md .gitattributes; do
  diff -q "$tmp/$f" "$REPO_ROOT/$f" >/dev/null || fail "drift: $f differs from generator output"
done
# 4. drop stale worker-timeout stashes (self-healing on re-enable)
while git stash list | grep -q 'worker-timeout'; do
  idx="$(git stash list | grep 'worker-timeout' | head -1 | cut -d: -f1)"
  git stash drop "$idx" >/dev/null
done

  1. Dropped the 2 stale worker-timeout stashes (done by the gate itself at re-enable; verified gone afterward).

  2. Locked with a Go test suite — hygiene_test.go (9 tests) so any future regression reopens Gate 11 in CI.

Evidence & signatures

All verification ran in the actual repo, not just by inspection:

- **Gate 11 re-enable run** (with the 2 stale `worker-timeout` stashes recreated first):
  ```
  GATE11 ok: present and non-empty: SUPPORT.md / CODE_OF_CONDUCT.md / .gitattributes
  GATE11 ok: required content markers present
  GATE11 ok: committed docs match generator output (no drift)
  GATE11 ok: dropped stale worker-timeout stash(es)
  GATE11 ok: no stale worker-timeout stashes
  GATE 11 CLOSED: release hygiene verified.
  ```
  Stash list went from `stash@{0} worker-timeout: test artifact cleanup` + `stash@{1} worker-timeout: warm build cache` to **empty**; `git status` clean afterwards (idempotency confirmed — regeneration changed nothing).
- **`go vet ./...` clean; `go test -v ./...` → 9/9 PASS**: `TestGate11FilesExistAndNonEmpty`, `TestSupportContent`, `TestCodeOfConductContent`, `TestGitAttributesContent`, `TestLFOnlyInManagedTextFiles` (no CRLF, matching `eol=lf`), `TestGeneratorIdempotentAndDriftFree`, `TestGate11ScriptPasses`, `TestNoStaleWorkerTimeoutStashes`, `TestGateBlocksOnMissingFile`.
- **Edge cases tested:** (a) gate fails hard on a missing file — removing `SUPPORT.md` yields `GATE11 FAIL: missing SUPPORT.md`, exit 1, so re-enable can't be silently skipped again; (b) drift — the gate byte-compares committed docs to generator output, so hand-edited "mechanical" docs fail; (c) idempotency — generator run twice produces identical trees; (d) stale stashes — both dropped and asserted gone; (e) Windows/CRLF exposure — `eol=lf` rules verified against actual file bytes.
{"model": "deepseek-v4-flash", "problem_class": "go-docs-gate11-hygiene", "result": "passed", "tests": 9}
Generated from the verified corpus · MIT licensedBack to the catalog