diff --git a/community/00_contributing/05_project_management.mdx b/community/00_contributing/05_project_management.mdx index a3a28005..a92a2268 100644 --- a/community/00_contributing/05_project_management.mdx +++ b/community/00_contributing/05_project_management.mdx @@ -23,100 +23,87 @@ import useBaseUrl from "@docusaurus/useBaseUrl"; -## Project Tracker +## Linear Tracker -All work across the Z-Shell organization is tracked in a single unified project: +Planned, active, and deferred work across the Z-Shell organization is +prioritized in the **Z-Shell Workspace** project in Linear: - Z-Shell Tracker → + Open Linear →

-The project pulls issues and pull requests from every repository in the -[`z-shell`](https://github.com/z-shell) GitHub organization into one place, so -nothing slips through the cracks. +GitHub issues and pull requests remain the repository-level record for +discussion, implementation, and review. Linear provides the cross-repository +planning view: priority, status, ownership, estimates, cycles, and dependencies. -### Project Views +### Workflow -| View | Layout | Purpose | -| --- | --- | --- | -| **Triage** | Table | New items awaiting investigation — start here | -| **Bugs Board** | Board | Active bug work, grouped by Status | -| **Features Board** | Board | Feature and enhancement work | -| **Active Sprint** | Board | Everything in the current 2-week sprint | -| **Roadmap** | Roadmap | Planned work on a timeline | -| **By Repository** | Table | All items grouped by source repo | - -### Custom Fields +Each tracked item moves through the z-shell team's Linear workflow: -Each item in the project can have the following fields set: - -| Field | Values | Notes | -| --- | --- | --- | -| **Status** | Triage · Todo · In Progress · In Review · Done · Blocked · Won't Fix | Set by maintainers during triage | -| **Priority** | 🔴 Critical · 🟠 High · 🟡 Medium · 🔵 Low · None | | -| **Item Type** | Bug · Feature · Enhancement · Docs · Security · Performance · Chore · CI | | -| **Effort** | XS · S · M · L · XL | Rough size estimate | -| **Sprint** | Sprint 1 … Sprint N | 2-week iterations starting Mondays | +| Status | Purpose | +| --- | --- | +| **Backlog** | Accepted work that is not yet scheduled | +| **Todo** | Ready to begin | +| **In Progress** | Actively being implemented | +| **In Review** | Awaiting review, verification, or publication | +| **Done** | Completed and verified | +| **Canceled** | Deliberately removed from the plan | +| **Duplicate** | Covered by another tracked item | ### Triage Workflow -New issues and PRs are automatically added to the project with **Status = Triage**. -A maintainer reviews the item and: +When work is added to Linear, a maintainer: -1. Sets **Item Type** (Bug, Feature, etc.) -2. Sets **Priority** -3. Moves **Status** to `Todo` (or `Won't Fix` / `Blocked` if appropriate) -4. Assigns to a **Sprint** if it should be worked on soon -5. Adds the appropriate [label](#labels) +1. Links the owning GitHub issue or pull request when one exists. +2. Sets its **Priority**, **Status**, and project. +3. Adds labels and an estimate when they improve planning. +4. Records dependencies so blocked work is visible. +5. Assigns it to a cycle only when it is ready to schedule. ### Capturing Deferred Work Do not leave postponed work only in local diffs, review notes, or memory. -Create or update an issue in the repository that owns the work so it is added to -the shared tracker automatically. +Create or update an issue in the repository that owns the work, then add or link +the corresponding Linear item when the task needs cross-repository planning. When splitting or deferring work: 1. Create **one issue per logical task** so each item can be prioritized and completed independently. 2. Include enough context for another maintainer to resume later: the observed problem, why it matters, relevant files, and any known constraints. -3. Suggest the likely **Item Type**, **Priority**, and **Effort** during triage. +3. Suggest the likely **Priority**, estimate, and initial Linear status during triage. 4. Use the canonical labels instead of repo-local tracking conventions. -### Sprint Cadence - -Sprints run for **2 weeks**, starting every other Monday. - -At the end of each sprint, incomplete items are moved to the next sprint or -returned to the backlog (`Todo` without a sprint assignment). - ### Priority Definitions | Priority | Meaning | | --- | --- | | 🔴 **Critical** | Data loss, security vulnerability, or complete breakage with no workaround | -| 🟠 **High** | Significantly impacts users; should be in the current or next sprint | -| 🟡 **Medium** | Important but not urgent; planned within the next few sprints | +| 🟠 **High** | Significantly impacts users or blocks important work; schedule next | +| 🟡 **Medium** | Important but not urgent; prioritize against other planned work | | 🔵 **Low** | Nice to have; no fixed timeline | | **None** | Not yet triaged or genuinely optional | -### Automation +### GitHub and Linear -Every repository in the organization has a `.github/workflows/project-tracker.yml` -workflow that automatically adds new issues and pull requests to the project. No -manual steps are required from contributors. +Contributors should continue opening issues and pull requests in the owning +GitHub repository. Maintainers use Linear to coordinate work that spans +repositories, needs scheduling, or should remain visible after it is deferred. +Links between the two systems preserve the implementation history without +duplicating long-form technical context. --- ## Labels All repositories in the `z-shell` organization use the same canonical label set. -Labels are applied automatically by the stale bot or manually during triage. +Labels are applied manually during triage or by approved organization +automation. The source of truth lives in [`z-shell/.github/.github/lib/labels.yml`](https://github.com/z-shell/.github/blob/main/.github/lib/labels.yml). diff --git a/community/00_contributing/index.mdx b/community/00_contributing/index.mdx index e7978367..e255fbef 100644 --- a/community/00_contributing/index.mdx +++ b/community/00_contributing/index.mdx @@ -68,7 +68,7 @@ Choose the path that matches what you want to do: | --- | --- | | 👥 Join the team | [Open a membership request](https://github.com/z-shell/.github/issues/new?assignees=&labels=type%3A+membership%2Carea%3A+meta&template=05_membership.yml&title=team%3A+) | | 🌐 Translate | [translate.zshell.dev](https://translate.zshell.dev) | -| 📋 Project tracker | [Z-Shell Tracker](https://github.com/orgs/z-shell/projects/28) | +| 📋 Project tracker | [Linear](https://linear.app/ss-o/project/z-shell-workspace-0206c6a7192d) | | 💬 Discuss | [GitHub Discussions](https://github.com/z-shell/zi/discussions) | ## General Guidelines diff --git a/community/index.mdx b/community/index.mdx index db1a9fbe..b3b81549 100644 --- a/community/index.mdx +++ b/community/index.mdx @@ -29,7 +29,7 @@ The Z-Shell community is home to contributors, plugin authors, and Zsh enthusias :::info[Get involved] -Join the [Z-Shell organization](https://github.com/z-shell), help [translate the wiki](https://translate.zshell.dev), or track work in the [Z-Shell Tracker](https://github.com/orgs/z-shell/projects/28). +Join the [Z-Shell organization](https://github.com/z-shell), help [translate the wiki](https://translate.zshell.dev), or track work in the [Z-Shell Workspace](https://linear.app/ss-o/project/z-shell-workspace-0206c6a7192d). ::: ## Community Sections diff --git a/static/img/svg/community/contributing-project-management.svg b/static/img/svg/community/contributing-project-management.svg index d9cf2752..6ca70e1e 100644 --- a/static/img/svg/community/contributing-project-management.svg +++ b/static/img/svg/community/contributing-project-management.svg @@ -18,7 +18,7 @@ - Z-Shell Tracker + Linear Tracker