📋 Project Management
Project Tracker
All work across the Z-Shell organization is tracked in a single unified project:
Z-Shell Tracker →
The project pulls issues and pull requests from every repository in the
z-shell GitHub organization into one place, so
nothing slips through the cracks.
Project Views
| 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 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 |
Triage Workflow
New issues and PRs are automatically added to the project with Status = Triage. A maintainer reviews the item and:
- Sets Item Type (Bug, Feature, etc.)
- Sets Priority
- Moves Status to
Todo(orWon't Fix/Blockedif appropriate) - Assigns to a Sprint if it should be worked on soon
- Adds the appropriate label
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.
When splitting or deferring work:
- Create one issue per logical task so each item can be prioritized and completed independently.
- Include enough context for another maintainer to resume later: the observed problem, why it matters, relevant files, and any known constraints.
- Suggest the likely Item Type, Priority, and Effort during triage.
- 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 |
| 🔵 Low | Nice to have; no fixed timeline |
| None | Not yet triaged or genuinely optional |
Automation
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.
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.
The label set is maintained by
scripts/sync-labels.sh
in z-shell/src — run it to re-sync labels after adding a new repository.
Type Labels
Use these to describe what kind of work an issue or PR represents.
| Label | Color | Description |
|---|---|---|
bug 🐛 |  #d73a4a | Something isn't working |
feature-request 💡 |  #0075ca | New feature or request |
enhancement ✨ |  #a2eeef | Improvement to existing functionality |
documentation 📝 |  #0052cc | Documentation-only changes |
performance 🚀 |  #006b75 | Performance improvements |
security 🛡️ |  #ee0701 | Security vulnerability or hardening |
breaking-change 💥 |  #d93f0b | Breaks backward compatibility |
dependencies 📦 |  #0366d6 | Dependency updates |
chore 🔧 |  #c5def5 | Routine maintenance, no behavior change |
refactor ♻️ |  #5319e7 | Code refactor, no behavior change |
ci ⚙️ |  #1d76db | CI/CD pipeline changes |
Status / Workflow Labels
Use these to describe where an issue stands in the process.
| Label | Color | Description |
|---|---|---|
triage 🔍 |  #fbca04 | Needs investigation before action |
in-progress 🚧 |  #f9d0c4 | Currently being worked on |
blocked ⛔ |  #e4e669 | Blocked on external dependency/decision |
stale 💤 |  #f2f2f2 | No activity for an extended period |
invalid ⚠️ | #e4e669 | Off-topic, cannot reproduce, or incorrect |
wontfix 🚫 |  #ffffff | Will not be fixed |
no-stale 🔒 |  #0e8a16 | Exempt from stale-bot closing |
Community Labels
| Label | Color | Description |
|---|---|---|
help-wanted 🙋 |  #008672 | Extra attention or expertise needed |
good-first-issue 🌱 |  #7057ff | Good for newcomers |
Q&A ✍️ |  #d4c5f9 | Questions and answers |
Syncing Labels
To apply the canonical label set to a repository:
# Single repo
echo "my-repo" > /tmp/repos.txt
./scripts/sync-labels.sh z-shell /tmp/repos.txt
# All org repos
./scripts/sync-labels.sh z-shell scripts/repos.txt
The --force flag means existing labels with the same name are updated to match
the canonical color and description. Labels not in the canonical set are not
deleted automatically — remove them manually if desired.