Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

docs(contributing): clarify fork-based contributions for agents

Open
  • Is something wrong?
#1,870 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
1-2 days
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
git, github
Domain
documentation

Research direction

Start with the Step 3 section of CONTRIBUTING.md and the Commands section of skills/branch-pr/SKILL.md, which show the branch, git push -u origin and gh pr create sequence, then check AGENTS.md for how agents are pointed to them. The work is to document how to verify fork and upstream remotes and base branches, and when an agent must stop for a maintainer decision. The issue says a maintainer must first establish the supported procedure, so confirm that before writing anything. Done means the two documents agree and no workflow conflicts with CONTRIBUTING.md.

Written by the indexing model from the issue text.

Description

status:needs-review type:docs
Existing Issue Search
  • I searched existing issues and will add evidence to a canonical tracker when applicable.

Bounded searches covered GH013, fork/contributing/contribution titles, contribution-workflow phrases, stacked/chained titles, and docs-labelled fork reports. No equivalent tracker was found in those searches; this is not a claim of exhaustive absence. Closed #1359 covered only the navigation link from AGENTS.md to CONTRIBUTING.md, not the operational guidance below.

📄 Documentation Reference
📄 Which Document?

CONTRIBUTING.md and a skill in skills/ (skills/branch-pr/SKILL.md).

🔍 Observed Consequence

Contribution guidance already exists: CONTRIBUTING.md requires an approved, assigned issue, instructs contributors to fork the repository and create a branch from main, and requires a linked PR with one canonical type label. AGENTS.md points agents to that guide. The problem is missing operational guidance, not the absence of a contribution workflow.

The PR skill's command example starts with a branch from main, then uses git push -u origin ... and gh pr create, without explaining how to establish or verify fork/upstream remotes or what repository origin must identify. A contributor or agent cannot determine from this example whether the intended destination has been selected safely, or how to update the fork's main before branching.

The checked documentation also does not explain how to keep a dependent PR chain reviewable when its heads are in a fork: which repository must own each base branch, what supported delivery strategies and prerequisites apply, and when a contributor must stop for a maintainer decision rather than assume an upstream parent branch exists.

This ambiguity was encountered while preparing #1348. Four ordinary, non-force pushes of new contribution branches directly to upstream were rejected with GH013 and 6 of 6 required status checks are expected. A read-only reconciliation confirmed that none of the four branches or PRs had been created. The observed upstream pr ruleset (13932028) applied to all branches and enforced those checks on creation (do_not_enforce_on_create=false); the current account could not bypass it. This records the observed rejection, not a request to disable checks or a claim that a fork route has already been validated.

The checked docs did not provide a safe next step for that initial-branch rejection. Agents must not infer permission to retry, switch repositories, use exempt branch namespaces, fabricate checks, or alter rules.

Release Context

Repository contribution/documentation workflow, not a released Engram runtime version. Documentation and remote main were checked at f3f5aa789b0fcc5fcb520b4a1b910bbf1611655c.

💡 Desired Outcome

Contributors, including agents, should be able to:

  • Identify and verify the fork and upstream repositories, remote names, default/main branch and intended head/base before publication; understand how the fork's main is kept current.
  • Understand the supported way to deliver dependent reviewable PR slices from a fork, including base-branch ownership and any maintainer prerequisites or limitations.
  • Recognize an initial-branch GH013 rejection and know when to stop and request an authorized publication route, without bypassing controls or silently changing destinations.
  • Distinguish authorization for creating/using a fork, pushing branches, opening or updating upstream PRs, and merging; an agent must not treat one action as blanket authority for the others.

Keep the contribution policy maintained in CONTRIBUTING.md and align the agent-facing skill with it, rather than introducing contradictory parallel workflows.

📎 Additional Context
  • #1359 is related navigation work, not an equivalent operational-guidance issue.
  • #1348 supplied the observed contribution occurrence; its implementation and publication decision remain separate.
  • Scope: documentation and agent-facing guidance only. No code changes, ruleset/permission changes, status-check weakening, bypasses, fork creation, push retries, PR publication or merge are requested by this issue.
  • A maintainer should establish the supported procedure; this report intentionally does not prescribe an unverified workaround.
Dominant language
Go
Stars
7.1k
Forks
729
Avg merge
10h 43m
Merged PRs (30d)
332

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Gentleman-Programming/engram

All issues in Gentleman-Programming/engram

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.