diff --git a/CHANGELOG.md b/CHANGELOG.md index 43961cf..22fb2d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,21 @@ and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) conventions. Commit message format is enforced via [commitlint](https://commitlint.js.org/) starting with v0.2.0. > **How to update this file** -> Run `npm run generate:client` after any API surface change and bump the version -> in `package.json`. Add your changes under `[Unreleased]` as you work; entries -> are moved to a versioned section on release. +> +> Add entries to the `[Unreleased]` section as you work on features and fixes. +> Organize by subsection (`Added`, `Fixed`, `Removed`, etc.) as defined below. +> +> **Mapping from Conventional Commits:** +> - `feat(scope): ...` → `[Added]` +> - `fix(scope): ...` → `[Fixed]` +> - `perf(scope): ...` → `[Changed]` (with note about performance improvement) +> - `refactor(scope): ...` → `[Changed]` (with scope of refactoring) +> - `docs(scope): ...` → `[Documentation]` (if user-facing; skip if internal only) +> - `chore(scope): ...` → Skip (internal tooling, no user-visible change) +> +> On version release, the `[Unreleased]` section is renamed to `[X.Y.Z]` with the +> release date, and a new `[Unreleased]` section is created. Version must be bumped +> in `package.json` to match. --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53d9300..5ed0691 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -382,6 +382,81 @@ The CI job `commitlint` checks the PR title on every pull request. Squash merges are preferred so that the merge commit title is the canonical changelog entry. +### Updating the changelog + +When working on a feature or fix that affects users, add an entry to `CHANGELOG.md` +under `[Unreleased]` before opening your PR: + +| Commit Type | Changelog Section | Example | +|-------------|-------------------|---------| +| `feat(...)` | `Added` | A new endpoint or behavior | +| `fix(...)` | `Fixed` | A bug fix or behavioral correction | +| `perf(...)` | `Changed` | Performance improvement | +| `refactor(...)` | `Changed` | Major structural change affecting users | +| `docs(...)` | `Documentation` | User-facing documentation changes | +| `chore(...)` | — | Skip (internal tooling, no user-visible change) | +| `test(...)` | — | Skip (internal tests, no user-visible change) | + +For details on changelog format and section definitions, see the instructions in +`CHANGELOG.md`. + +--- + +## GitHub issue labels + +When creating or triaging GitHub Issues, use the label taxonomy defined in +[docs/LABEL_TAXONOMY.md](./docs/LABEL_TAXONOMY.md) to categorize work by difficulty +and area. This helps contributors discover work that matches their skill level and +interest. + +### Quick reference + +- **`good-first-issue`** — Suitable for newcomers; isolated, self-contained, no major + prerequisites blocking +- **`help-wanted`** — Open to anyone; clear scope but could benefit from fresh eyes +- **`category/*`** — Categorize by area: `category/backend`, `category/security`, + `category/devops`, `category/governance` +- **`status/*`** — Track lifecycle: `status/in-progress`, `status/blocked`, + `status/ready-to-merge` + +For detailed mapping rules (e.g. how to label issues from the contributor backlog), +see [docs/LABEL_TAXONOMY.md](./docs/LABEL_TAXONOMY.md). + +## Drips Wave contributor accounting + +This project offers a points-based contributor incentive program (Drips Wave). +Contributors who close issues earn points that are recorded in a ledger. + +### How points are awarded + +Every issue in the contributor backlog has a fixed point value: +- **High complexity**: 200 points +- **Medium complexity**: 150 points + +When your PR closes an issue, the points for that issue are credited to your contributor account. +See [docs/DRIPS_WAVE_LEDGER.md](./docs/DRIPS_WAVE_LEDGER.md) for the full ledger and accounting rules. + +### For PR authors + +When you open a PR that solves an issue from the backlog, include a `Closes` tag in your +PR description to link the PR to the issue number: + +```markdown +## Description + +Brief description of the changes. + +Closes # +``` + +This creates an auditable record that ties your PR to a specific point value. The ledger +is updated when the PR is merged. + +### Disputes and escalation + +If there's a disagreement about points, attribution, or the ledger record, see the +escalation process in [docs/DRIPS_WAVE_LEDGER.md](./docs/DRIPS_WAVE_LEDGER.md). + --- ## Submitting a pull request diff --git a/docs/DRIPS_WAVE_LEDGER.md b/docs/DRIPS_WAVE_LEDGER.md new file mode 100644 index 0000000..5520d16 --- /dev/null +++ b/docs/DRIPS_WAVE_LEDGER.md @@ -0,0 +1,65 @@ +# Drips Wave Contributor Ledger + +This document records contributions to the vortex-backend contributor incentive program (Drips Wave), tracking issue numbers, contributors, merge dates, and points awarded. + +## Format + +| Merge Date | PR | Contributor | Issue Number | Issue Title | Points | Notes | +|------------|-----|-------------|--------------|-------------|--------|-------| +| YYYY-MM-DD | #XXX | @username | #N | Short description | 150/200 | Any special context | + +## Ledger + +### Phase 1 (Q3 2026) + +_(Initial seed batch — to be populated as first wave of issues are completed)_ + +## Accounting Rules + +### Point Values + +- **High complexity**: 200 points +- **Medium complexity**: 150 points + +Complexity levels are defined in `issues.md` (upstream) and referenced in GitHub Issue descriptions. + +### Source of Truth + +Each PR must reference an issue number in its description: +``` +Closes # +``` + +This creates a verifiable link between the merged PR and the `issues.md` entry, enabling automated or manual ledger updates. + +### Recording Process + +1. **PR opens**: Author ensures the description includes `Closes #` +2. **PR merged**: Merge commit title captures the change; the linked issue is the join key +3. **Ledger update**: A maintainer (or automated CI job, if implemented) adds a row to this ledger + +The ledger is append-only; rows are not deleted or modified once recorded. + +### Dispute Resolution + +Disputes about point allocation or contributor attribution follow the escalation ladder in +[CODE_OF_CONDUCT.md](https://github.com/vortex-protocol/.github/blob/main/CODE_OF_CONDUCT.md): + +1. **Clarification**: Poster of ledger entry and contributor agree on facts +2. **Maintainer review**: If disagreement persists, a maintainer with push access reviews the issue and PR +3. **Escalation**: Unresolved disputes are brought to the team lead for final decision + +Changes to the ledger (if any are needed) are documented in a follow-up commit with reasoning. + +## Notes + +- This ledger is not a replacement for contributor recognition elsewhere (e.g. GitHub's contributor graph, release notes) +- Point totals do not automatically convert to payments or rewards; that is handled separately and outside this repository +- Ledger entries are public and auditable; disputes and resolutions are also documented publicly + +--- + +For more context on the Drips Wave program, see: +- `issues.md` (upstream, in vortex-protocol/.github) — defines issues and point values +- [CONTRIBUTING.md](./CONTRIBUTING.md) — contributor workflow +- `CHANGELOG.md` — user-facing changes diff --git a/docs/LABEL_TAXONOMY.md b/docs/LABEL_TAXONOMY.md new file mode 100644 index 0000000..395a7a8 --- /dev/null +++ b/docs/LABEL_TAXONOMY.md @@ -0,0 +1,77 @@ +# Label Taxonomy and Issue Management + +## Overview + +This document defines the label taxonomy for GitHub Issues, used to categorize contributor work from `issues.md` and help new contributors discover work that matches their skill level. + +## Label Categories + +### Difficulty Labels + +Used to indicate the expected difficulty and prerequisite knowledge for a given issue. + +| Label | Color | Description | Candidates | +|-------|-------|-------------|-----------| +| `good-first-issue` | `#7057ff` | Suitable for newcomers with no major prerequisites; isolated, self-contained scope | Medium complexity issues with no unresolved High-complexity prerequisites | +| `help-wanted` | `#008672` | Open to anyone; may have a clear scope but could benefit from fresh eyes or bandwidth | Any complexity level without critical-path blocking | +| `hard` | `#d73a49` | Significant challenge; may require deep codebase knowledge or non-trivial design work | High complexity issues; new architectural patterns | + +### Category Labels + +Mirror the four implicit categories in `issues.md`: + +| Label | Color | Description | +|-------|-------|-------------| +| `category/backend` | `#c2e0c6` | Backend API, services, database, integrations | +| `category/security` | `#fc2929` | Security audit, vulnerability disclosure, authentication | +| `category/devops` | `#1d76db` | Infrastructure, CI/CD, monitoring, operations | +| `category/governance` | `#ffc274` | Community, documentation, process, contributor onboarding | + +### Status Labels + +Track issue lifecycle: + +| Label | Color | Description | +|-------|-------|-------------| +| `status/blocked` | `#d73a49` | Cannot proceed; describes blocker in the issue or comment | +| `status/in-progress` | `#0075ca` | Being actively worked on; PR referenced in issue or comment | +| `status/ready-to-merge` | `#a2eeef` | Approved PR awaiting merge; linked PR should reference issue number | + +## Mapping Rules + +### From `issues.md` to GitHub Issues + +When mirroring an issue from `issues.md` to GitHub: + +1. **Title**: Use the issue's `[DESCRIPTION]` line verbatim +2. **Body**: Include the full `[DESCRIPTION]` + `[PROBLEM STATEMENT & CONTEXT]` sections; link back to `issues.md` +3. **Category Label**: Determine from the issue's category in `issues.md`; apply one of `category/backend`, `category/security`, `category/devops`, or `category/governance` +4. **Difficulty Label**: Apply based on Complexity + prerequisites: + - **`good-first-issue`**: If Complexity is `Medium` AND the issue description does not reference any High-complexity issue numbers as prerequisites + - **`help-wanted`**: If the issue is open and not currently assigned, and is not blocked by another open issue + - **`hard`**: If Complexity is `High`, always apply (in addition to category label) +5. **Prerequisites**: In the issue body, add a "Prerequisites" section listing any dependent issues (those referenced in Implementation Guidelines or Problem Statement) + +**Example**: Issue #25 in `issues.md` is "Medium" complexity in Backend, doesn't reference a High blocker → `category/backend` + `good-first-issue` + +### Exclusion Rules + +Do **not** mark an issue as `good-first-issue` if: +- Any of its prerequisites are still open +- It requires significant cross-module refactoring +- Its description includes "TODO: [document the unfinished design]" or similar + +## Maintenance + +- When an issue is closed (PR merged), remove the `help-wanted` label if present +- When an issue moves to active work, add `status/in-progress` and reference the PR +- When a PR is approved, add `status/ready-to-merge` (removed on merge) +- Review labels quarterly as the backlog evolves + +## Initial Seed Batch + +The first batch of issues mirrored from `issues.md` (issues #316–#330) should include examples from all categories and both difficulty levels to establish a clear pattern for future contributors. + +--- + +For more context on how the contributor backlog is managed, see [CONTRIBUTING.md](./CONTRIBUTING.md) and [issues.md](./issues.md) in the upstream repository.