Skip to content

.github: fix frontpage README overridden by .github/README.md#20168

Closed
anacrolix wants to merge 4 commits intomainfrom
anacrolix/fix-frontpage-readme
Closed

.github: fix frontpage README overridden by .github/README.md#20168
anacrolix wants to merge 4 commits intomainfrom
anacrolix/fix-frontpage-readme

Conversation

@anacrolix
Copy link
Copy Markdown
Contributor

@anacrolix anacrolix commented Mar 26, 2026

What

GitHub renders .github/README.md in preference to the root README.md, so the repository front page was showing CI guidelines instead of the Erigon project overview.

  • Delete .github/README.md and .github/PROPOSAL.md
  • Combine their content into CI-GUIDELINES.md at the repo root, reorganised around four explicit trigger buckets
  • Update references in agents.md / CLAUDE.md

CI guidelines restructure

The guidelines are now organised around four buckets with explicit contracts:

Bucket Trigger Contract
Pull request pull_request Fast signal on things devs cannot easily check locally
Merge queue merge_group Deterministic gate — failure means the code is wrong
Push to main/release push to main/release/** Cache warming only — no test validation
Scheduled schedule Long-running or repeated runs not feasible on every commit

Current state of CI and open problems

Flaky tests running on main and release branches

Several tests that fail intermittently are currently triggered on main and release
branches. This causes two problems:

  1. During PRs — a flaky failure blocks the PR or forces a re-run, wasting time and
    eroding confidence in the CI signal.
  2. After merge — a failure on main or a release branch cannot be corrected. There
    is no PR to fix, no author to notify, and no way to amend the commit. To outside
    observers the branch simply looks broken.

The preferred remedy is to move flaky tests to the PR bucket, where failures are visible
to the author and can be prioritised. Failures on a PR are contained; failures on main
are permanent and public.

Options on the table:

  • Fix the tests. Make them deterministic so they can be promoted to the merge queue.
  • Move them to PR checks. Flaky failures on a PR surface the problem to the right
    person at the right time, rather than polluting main.
  • Run merge queue jobs multiple times. GitHub's merge queue supports retrying jobs
    before deciding on a result. This can absorb occasional flakiness but increases queue
    latency and is not a long-term solution — it masks the problem rather than fixing it.
  • Non-blocking visibility checks. It is possible to run a job without blocking the
    merge. However, this does not help with the main/release branch problem: a
    non-blocking failure still shows up on the commit, still signals low-quality code to
    outside observers, and still cannot be corrected.

Failure visibility and attribution

When a scheduled workflow fails, there is currently no reliable link between the failure
and the commit that introduced it. QA collects and reports on scheduled failures, but
addressing them is not a visible development priority because the failure does not appear
on the commit itself.

One proposal is to use an alternate GitHub token to retroactively post a commit status
or check run against the specific commit that first introduced the regression. This would
surface the failure at the point where it landed rather than at the point the scheduled
job happened to run, making it harder to defer.

GitHub renders .github/README.md in preference to the root README.md,
so the repository front page was showing CI guidelines instead of the
project overview.

Combine .github/README.md and .github/PROPOSAL.md into CI-GUIDELINES.md
at the repo root and update references.
Replace the trigger ladder with four explicit buckets (pull request,
merge queue, push to main/release, scheduled), each with a clear
contract. Add guidance on flaky test placement, cache-warming-only
push runs, and scheduled failure attribution.
@anacrolix anacrolix closed this Mar 27, 2026
@anacrolix anacrolix deleted the anacrolix/fix-frontpage-readme branch March 27, 2026 01:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant