From 116646445bdbcc0a47cade12f16d409e59f32ead Mon Sep 17 00:00:00 2001 From: vickman787 Date: Wed, 29 Jul 2026 09:52:43 +0100 Subject: [PATCH] docs: add issue application guidance (Closes #98) Adds docs/ISSUE_APPLICATION_GUIDE.md covering how to apply for an issue, example application comments, the assignment-before-work rule, PR linking expectations, and maintainer assignment notes, aligned with the existing auto-assign workflow. Links it from the README docs index and the contributor guide. --- README.md | 1 + docs/CONTRIBUTOR_GUIDE.md | 7 ++ docs/ISSUE_APPLICATION_GUIDE.md | 193 ++++++++++++++++++++++++++++++++ 3 files changed, 201 insertions(+) create mode 100644 docs/ISSUE_APPLICATION_GUIDE.md diff --git a/README.md b/README.md index 03f96cc..838d723 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,7 @@ All of these live under [`./docs/`](./docs/). | Shared test fixtures | [`FIXTURE_FRAMEWORK.md`](./docs/FIXTURE_FRAMEWORK.md) | | Status severity mapping | [`STATUS_SEVERITY_MAPPING.md`](./docs/STATUS_SEVERITY_MAPPING.md) | | Contributor guide | [`CONTRIBUTOR_GUIDE.md`](./docs/CONTRIBUTOR_GUIDE.md) | +| Issue application guide | [`ISSUE_APPLICATION_GUIDE.md`](./docs/ISSUE_APPLICATION_GUIDE.md) | | Meaningful vs. insufficient contribution examples | [`MEANINGFUL_WORK_EXAMPLES.md`](./docs/MEANINGFUL_WORK_EXAMPLES.md) | | Meaningful implementation checklist | [`MEANINGFUL_IMPLEMENTATION_CHECKLIST.md`](./docs/MEANINGFUL_IMPLEMENTATION_CHECKLIST.md) | | Low-effort contribution examples | [`LOW_EFFORT_CONTRIBUTION_EXAMPLES.md`](./docs/LOW_EFFORT_CONTRIBUTION_EXAMPLES.md) | diff --git a/docs/CONTRIBUTOR_GUIDE.md b/docs/CONTRIBUTOR_GUIDE.md index 74ad9f7..3ba82f1 100644 --- a/docs/CONTRIBUTOR_GUIDE.md +++ b/docs/CONTRIBUTOR_GUIDE.md @@ -18,6 +18,13 @@ technical, constructive, and respectful. Start with the [DEVELOPER_JOURNEY.md](./DEVELOPER_JOURNEY.md) walkthrough to understand how the monorepo modules fit together before diving into an issue. +## Applying for an issue + +Before commenting on any issue, read the [ISSUE_APPLICATION_GUIDE.md](./ISSUE_APPLICATION_GUIDE.md). +It covers how to write an application comment, the assignment-before-work rule, how to keep the +issue thread useful while you're assigned, and how to link your PR back to the issue — for both +regular issues and GrantFox campaign issues. + ## GrantFox campaign contributors If you are contributing through a GrantFox campaign, read diff --git a/docs/ISSUE_APPLICATION_GUIDE.md b/docs/ISSUE_APPLICATION_GUIDE.md new file mode 100644 index 0000000..5bc4718 --- /dev/null +++ b/docs/ISSUE_APPLICATION_GUIDE.md @@ -0,0 +1,193 @@ +# Issue application guide + +This document explains how to apply to work on an open AnchorKit issue: what to say in your +application comment, when you're allowed to start work, how to keep the issue thread useful +while you're assigned, and how to link your PR back to the issue. It applies to **every** +AnchorKit issue, not only GrantFox campaign issues. + +> **Key rule:** Comment and wait for an assignee before opening a PR. Unassigned, unsolicited +> PRs slow down review and may be closed without a full review. + +## Table of contents + +1. [Who this is for](#1-who-this-is-for) +2. [How to apply](#2-how-to-apply) +3. [Example application comments](#3-example-application-comments) +4. [Assignment-before-work rule](#4-assignment-before-work-rule) +5. [While you're assigned](#5-while-youre-assigned) +6. [PR linking expectations](#6-pr-linking-expectations) +7. [Submitting your PR](#7-submitting-your-pr) +8. [Maintainer assignment notes](#8-maintainer-assignment-notes) +9. [Common mistakes](#9-common-mistakes) +10. [Related documentation](#10-related-documentation) + +--- + +## 1. Who this is for + +- First-time contributors looking for a `good first issue`. +- Regular contributors picking up `bug`, `enhancement`, or `documentation` issues. +- GrantFox campaign contributors applying for issues labelled `GrantFox OSS` + + `Maybe Rewarded` + `Official Campaign | FWC26`. Read this guide first, then read + [GRANTFOX_WORKFLOW.md](./GRANTFOX_WORKFLOW.md) for the reward-specific rules on top of it. + +If an issue does not carry the GrantFox labels, everything in this guide still applies except +the reward-readiness review — it's simply a normal open-source contribution. + +--- + +## 2. How to apply + +1. Read the full issue body before commenting, including Acceptance Criteria and any + "Out of scope" section. See [ISSUE_STANDARD.md](./ISSUE_STANDARD.md) for the format + maintainers use when writing issues. +2. Check the **Assignees** field. If someone is already assigned, don't apply — comment + only if you have a clarifying question, or look for a different issue. +3. Post a single comment on the issue containing: + - **Relevant experience** — a sentence or two on background that applies to this issue + (prior Stellar/Soroban/TypeScript work, links to past contributions). + - **Approach** — a short bullet list of the files or modules you expect to touch and your + high-level plan. + - **Timeline** — when you expect to open a draft PR. +4. Wait for a maintainer to reply. Do not start implementation before that reply (see + [Section 4](#4-assignment-before-work-rule)). + +--- + +## 3. Example application comments + +**Good first issue / general bug fix:** + +> Hi, I'd like to work on this. I've fixed a couple of small TypeScript bugs in +> `packages/stellar-kit` before (see PR #53). My plan is to update `mapHorizonError` in +> `packages/stellar-kit/src/errors.ts` to handle the new status code and add a Vitest case +> for it. I can have a draft PR up within 2 days. + +**Documentation issue:** + +> I'd like to take this one. I'll add the new page under `docs/`, link it from the README docs +> index table, and cross-reference the existing contributor guide so the two don't drift. +> Draft PR within a day. + +**GrantFox campaign issue** (see [GRANTFOX_WORKFLOW.md § 2](./GRANTFOX_WORKFLOW.md#2-application-process) +for the full three-part format this campaign requires): + +> **Experience:** I've built two Soroban contracts for a Stellar DEX and contributed to the +> `@stellar/stellar-sdk` TypeScript bindings. +> +> **Approach:** +> - Add `SOURCE_NETWORK_ERROR` to `StellarErrorCode` in `packages/types/src/index.ts` +> - Update `mapHorizonError` to map timeout errors to the new code +> - Add Vitest cases for both network timeout and connection refused +> +> **Timeline:** First PR draft within 2 days. + +What makes these applications useful to a maintainer: they're specific about *what* will +change, not just *that* the contributor wants to help. "I'd like to work on this" with nothing +else is not an actionable application — a maintainer cannot judge fit or assign confidently +from it alone. + +--- + +## 4. Assignment-before-work rule + +- **Do not open a PR before you are assigned.** Assignment is what a maintainer uses to signal + "yes, go ahead" — it avoids two contributors duplicating work on the same issue, and for + GrantFox issues it's a precondition for reward-readiness review. +- Some repositories in this org run first-comment auto-assignment. See + [AUTO_ASSIGN_WORKFLOW.md](./AUTO_ASSIGN_WORKFLOW.md) for exactly when that applies, what the + automation checks before assigning you, and what happens if the automated assignment fails + (a maintainer completes it manually — you don't need to do anything differently). +- If you're not sure whether you've been assigned, check the issue's **Assignees** field in the + GitHub sidebar, or wait for the confirmation comment. +- Draft PRs opened for early feedback are fine **after** assignment; opening one before + assignment doesn't skip the queue and may be closed with a note to apply first. + +--- + +## 5. While you're assigned + +- If you get blocked or need to pause, comment on the issue explaining the situation instead of + going quiet. Assignments with no activity for 14 days may be released back to the pool (see + [AUTO_ASSIGN_WORKFLOW.md § 6.5](./AUTO_ASSIGN_WORKFLOW.md#65-recover-from-a-stalled-assignment)). +- If the scope turns out to be different from what the issue describes, comment on the issue and + wait for maintainer sign-off before implementing the new scope — don't silently expand or + shrink it. +- Keep implementation questions on the issue thread (or the PR once it's open), not in DMs or + email, so the discussion stays visible to reviewers and other contributors. + +--- + +## 6. PR linking expectations + +- The PR title's first line should reference the issue number, e.g. `[#98] Add issue + application guidance`. +- The PR body **must** contain `Closes #NNN` or `Fixes #NNN` so the issue closes automatically + on merge. +- If a PR only partially addresses an issue, use `Refs #NNN` instead of `Closes #NNN` and say + so explicitly in the PR body — don't let a partial PR auto-close a not-yet-finished issue. +- Use the [PR template](../.github/PULL_REQUEST_TEMPLATE.md); GitHub pre-fills it automatically. + Fill in every section — mark items `N/A` rather than deleting them. + +--- + +## 7. Submitting your PR + +1. Fork the repo and branch from `main`: `feat/`, `fix/`, `docs/`, or + `chore/`. +2. Implement the change, add or update tests, and update the relevant `docs/*.md` file if the + change is user-facing. +3. Run `pnpm verify` locally before pushing (see [LOCAL_VERIFICATION.md](./LOCAL_VERIFICATION.md)). +4. Open the PR with the linking expectations from [Section 6](#6-pr-linking-expectations). +5. Respond to review feedback with new commits rather than force-pushing, so comment threads + stay intact. + +For the full contribution loop (setup, tests, security awareness), see +[CONTRIBUTOR_GUIDE.md](./CONTRIBUTOR_GUIDE.md). + +--- + +## 8. Maintainer assignment notes + +When reviewing an application comment: + +- Confirm the issue has no existing assignee before assigning a new applicant. +- A useful application names concrete files/modules and a plan — don't require the same + three-part format from [GRANTFOX_WORKFLOW.md](./GRANTFOX_WORKFLOW.md) on non-campaign issues, + but do expect more than "I'll take this." +- Reply on the issue thread with either an explicit assignment or a short, polite decline — + silence leaves the applicant unsure whether to wait or move on. +- If [auto-assign](./AUTO_ASSIGN_WORKFLOW.md) already handled the assignment, you don't need to + assign manually — just confirm it landed correctly and step in only for the failure cases + documented there. +- One assignee per issue. If you want to override the automated or first-accepted applicant in + favour of someone else, follow + [AUTO_ASSIGN_WORKFLOW.md § 6.4](./AUTO_ASSIGN_WORKFLOW.md#64-override-auto-assignment-for-a-maintainer-picked-contributor). +- See [MAINTAINER_GUIDE.md § GrantFox assignments](./MAINTAINER_GUIDE.md#grantfox-assignments) for + the campaign-specific assignment rules on top of the above. + +--- + +## 9. Common mistakes + +| Mistake | What to do instead | +|---------|--------------------| +| Opening a PR before being assigned | Comment to apply, wait for a maintainer reply | +| Applying with no plan ("I'll take this") | Name the files/modules you expect to touch and a rough timeline | +| Applying to an already-assigned issue | Check the Assignees field first; look for a different issue | +| Going quiet after being assigned | Comment on the issue if you're blocked or need more time | +| Omitting `Closes #NNN` from the PR body | Always link the issue so it closes on merge (or use `Refs #NNN` for partial work) | +| Expanding scope without asking | Comment on the issue and wait for approval before implementing beyond the stated scope | + +--- + +## 10. Related documentation + +- [GRANTFOX_WORKFLOW.md](./GRANTFOX_WORKFLOW.md) — full campaign application, review, and + reward-readiness process for GrantFox-labelled issues. +- [AUTO_ASSIGN_WORKFLOW.md](./AUTO_ASSIGN_WORKFLOW.md) — how first-comment auto-assignment + works and how maintainers recover from failure cases. +- [CONTRIBUTOR_GUIDE.md](./CONTRIBUTOR_GUIDE.md) — the full contribution loop: setup, testing, + security awareness, docs. +- [MAINTAINER_GUIDE.md](./MAINTAINER_GUIDE.md) — triage, review, and assignment responsibilities. +- [ISSUE_STANDARD.md](./ISSUE_STANDARD.md) — the format issues are expected to follow.