GitHub Issues Conventions

Core Principle

"Issues describe problems, commits describe solutions."

Write clear, actionable issues that anyone can pick up and understand. The issue title describes what's wrong or needed; labels and types handle categorization.

When to Use

Always use for:

• Creating new GitHub issues
• Reviewing issue quality before submission
• Planning work breakdown into trackable items
• Writing bug reports or feature requests

Skip for:

• Internal notes or comments
• Commit messages (use conventional commits instead)
• Quick discussions that don't need tracking

Issue Title Guidelines

Format: Plain, descriptive sentence case. No prefixes, no types, no emojis.

The title should describe the problem or need, not the solution. GitHub's issue types and labels handle categorization.

Good Titles

Bad Titles

Issue Types

Use GitHub's native issue type feature or labels to categorize:

Issue Body Templates

Bug Report

## Description
[Brief description of the bug]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [Third step]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- Browser: [e.g., Chrome 120]
- OS: [e.g., macOS 14.2]
- Service: [e.g., auth-service, frontend]

## Additional Context
[Screenshots, error messages, relevant logs]

Feature Request

## Problem Statement
[What problem does this solve? Why is it needed?]

## Proposed Solution
[High-level description of the feature]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Alternatives Considered
[Other approaches you thought about]

## Additional Context
[Mockups, examples from other products, related issues]

Task

## Context
[Background information and why this task exists]

## Requirements
[What needs to be done]

- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]

## Acceptance Criteria
- [ ] [How we know it's done - criterion 1]
- [ ] [How we know it's done - criterion 2]

## Technical Notes
[Implementation hints, constraints, related code]

## Related Issues
- #[related issue number]

Labels Convention

Use consistent labels across the KeyArc project for filtering and organization.

Priority Labels

priority:critical

priority:high

priority:medium

priority:low

Service Labels

service:auth

service:gateway

service:keys

service:account

service:frontend

Status Labels

status:ready

status:blocked

status:needs-info

status:in-progress

Scope Labels

scope:security

scope:api

scope:ui

scope:database

Organizing Work

GitHub provides organizational layers above individual issues. For KeyArc, use milestones and sub-issues to keep work structured without overhead.

Milestones

Use milestones to group issues toward a release or phase goal.

KeyArc Milestones:

When to use milestones:

• Release planning (what's in v1.0?)
• Phase tracking (what's left for Phase 1?)
• Sprint goals (if using time-boxed iterations)

Creating a milestone:

gh api repos/OWNER/REPO/milestones -f title="Phase 1: Auth & Core" -f description="Authentication service, database setup, and API gateway" -f due_on="2026-03-01T00:00:00Z"

Assigning issues to milestones:

gh issue edit 123 --milestone "Phase 1: Auth & Core"

Sub-issues

Use sub-issues to break down larger features or service implementations into trackable pieces.

Pattern: Create a parent issue for a major feature or service, then add sub-issues for individual tasks.

Example: Auth Service Implementation

Parent: Implement Auth Service (#10)
├── Sub: Create auth service project scaffold (#11)
├── Sub: Implement signup endpoint (#12)
├── Sub: Implement login endpoint (#13)
├── Sub: Add JWT token generation (#14)
├── Sub: Add password reset flow (#15)
└── Sub: Write auth service integration tests (#16)

Parent issue template:

## Overview
[High-level description of the feature or service]

## Sub-issues
This work is broken down into the following tasks:
- [ ] #11 - Create auth service project scaffold
- [ ] #12 - Implement signup endpoint
- [ ] #13 - Implement login endpoint
- [ ] #14 - Add JWT token generation
- [ ] #15 - Add password reset flow
- [ ] #16 - Write auth service integration tests

## Acceptance Criteria
- [ ] All sub-issues completed
- [ ] Service deployed to staging
- [ ] Integration tests passing

## Technical Notes
[Architecture decisions, constraints, links to docs]

When to use sub-issues:

• Service implementation (5+ related tasks)
• Complex features spanning multiple components
• Work that needs to be parallelized across contributors

When NOT to use sub-issues:

• Simple features (just use a single issue)
• Unrelated tasks (use labels/milestones instead)
• Bugs (usually standalone)

GitHub Project Board

KeyArc uses a GitHub Project board to track work status. Every issue must be added to the project board.

Project Reference:

• Project ID:

  PVT_kwDODzuJ-c4BNYGm

• Status Field ID:

  PVTSSF_lADODzuJ-c4BNYGmzg8Y71s

• Phase Field ID:

  PVTSSF_lADODzuJ-c4BNYGmzg8Y8FI

• Track Field ID:

  PVTSSF_lADODzuJ-c4BNYGmzg8Y8FM

• Project URL: https://github.com/orgs/KeyArc/projects/1

Field Options:

e5dd8d9b

a149a0a4

b3644764

9a932cb4

f3192413

acaef4ee

205962fc

e916e7bd

8612f72a

a28706f5

Complete Issue Creation Workflow

When creating a new issue, follow these steps:

Step 1: Create the issue with milestone and labels

gh issue create --repo KeyArc/keyarc \
  --title "Issue title here" \
  --body "Issue body..." \
  --milestone "Phase 1: Foundation" \
  --label "priority:high,track:dev,scope:infra"

Step 2: Add to project board

gh project item-add 1 --owner KeyArc --url https://github.com/KeyArc/keyarc/issues/ISSUE_NUMBER

Step 3: Set project fields (status, phase, track)

# Get the item ID first
ITEM_ID=$(gh project item-list 1 --owner KeyArc --format json | jq -r '.items[] | select(.content.number == ISSUE_NUMBER) | .id')

# Set status to Ready
gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_kwDODzuJ-c4BNYGm"
    itemId: "'"$ITEM_ID"'"
    fieldId: "PVTSSF_lADODzuJ-c4BNYGmzg8Y71s"
    value: {singleSelectOptionId: "e5dd8d9b"}
  }) { projectV2Item { id } }
}'

# Set phase (use option ID from Field Options table)
gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_kwDODzuJ-c4BNYGm"
    itemId: "'"$ITEM_ID"'"
    fieldId: "PVTSSF_lADODzuJ-c4BNYGmzg8Y8FI"
    value: {singleSelectOptionId: "acaef4ee"}
  }) { projectV2Item { id } }
}'

# Set track (use option ID from Field Options table)
gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_kwDODzuJ-c4BNYGm"
    itemId: "'"$ITEM_ID"'"
    fieldId: "PVTSSF_lADODzuJ-c4BNYGmzg8Y8FM"
    value: {singleSelectOptionId: "e916e7bd"}
  }) { projectV2Item { id } }
}'

Quick Reference Commands

Add issue to project:

gh project item-add 1 --owner KeyArc --url https://github.com/KeyArc/keyarc/issues/NUMBER

Update status to In Progress:

gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_kwDODzuJ-c4BNYGm"
    itemId: "ITEM_ID"
    fieldId: "PVTSSF_lADODzuJ-c4BNYGmzg8Y71s"
    value: {singleSelectOptionId: "b3644764"}
  }) { projectV2Item { id } }
}'

List project items with status:

gh project item-list 1 --owner KeyArc --format json | jq '.items[] | {number: .content.number, title: .content.title, status: .status}'

GitHub API Tips

Use

gh api

gh api repos/OWNER/REPO/issues -q '.[] | {number, title}'  # GET + jq
gh api repos/OWNER/REPO/issues/10/comments -X POST -f body="text"  # -f for strings
gh api repos/OWNER/REPO/issues/10/dependencies/blocked_by -X POST -F issue_id=123  # -F for integers

For project boards, use

gh api graphql -f query='mutation {...}'

Auto-unblock workflow:

.github/workflows/auto-unblock-issues.yml

Organizational Hierarchy

Milestone (Phase 1: Auth & Core)
├── Parent Issue: Implement Auth Service (#10)
│   ├── Sub-issue: Signup endpoint (#12)
│   ├── Sub-issue: Login endpoint (#13)
│   └── Sub-issue: JWT tokens (#14)
├── Parent Issue: Set up API Gateway (#20)
│   ├── Sub-issue: JWT validation (#21)
│   └── Sub-issue: Route configuration (#22)
└── Standalone Issue: Configure PostgreSQL (#5)

This gives you:

• Milestone view: "What's left for Phase 1?"
• Parent issue view: "What's left for Auth Service?"
• Individual issues: Assignable, trackable units of work

Good vs Bad Examples

Example 1: Bug Report

Bad:

Title: Login broken
Body: The login doesn't work sometimes. Please fix.

Good:

Title: Login fails when password contains ampersand character

## Description
Users cannot log in when their password contains an & character.

## Steps to Reproduce
1. Create account with password "Test&123"
2. Log out
3. Attempt to log in with same credentials

## Expected Behavior
Login succeeds with valid credentials

## Actual Behavior
Error: "Invalid credentials" even though password is correct

## Environment
- Browser: Chrome 120, Firefox 121
- OS: macOS 14.2

## Additional Context
Suspect URL encoding issue with special characters in authHash.

Example 2: Feature Request

Bad:

Title: Add notifications
Body: We need notifications for the app.

Good:

Title: Add email notifications for expiring API keys

## Problem Statement
Users have no way to know when their API keys are about to expire
unless they manually check the dashboard. This leads to service
outages when keys expire unexpectedly.

## Proposed Solution
Send email notifications at configurable intervals before key expiry:
- 30 days before (default)
- 7 days before
- 1 day before

## Acceptance Criteria
- [ ] User can configure notification preferences
- [ ] Emails sent at specified intervals before expiry
- [ ] Email contains key name, expiry date, and link to dashboard
- [ ] Respects user's notification opt-out preference

## Alternatives Considered
- In-app notifications only: Not helpful if user doesn't check app
- Slack integration: Too complex for v1, consider as future enhancement

Example 3: Task

Bad:

Title: Set up database
Body: Need to set up the database.

Good:

Title: Configure PostgreSQL database with Alembic migrations

## Context
The auth service needs a database to store user credentials and
encrypted vault keys. Using PostgreSQL for consistency with
architecture decisions.

## Requirements
- [ ] Create PostgreSQL instance on Fly.io
- [ ] Configure SQLAlchemy async engine
- [ ] Set up Alembic for migrations
- [ ] Create initial user table migration
- [ ] Add database health check endpoint

## Acceptance Criteria
- [ ] Service connects to database on startup
- [ ] Migrations run successfully
- [ ] Health check returns database status
- [ ] Connection pooling configured appropriately

## Technical Notes
- Use asyncpg driver for async support
- Follow existing SQLAlchemy patterns from src/shared/models/
- Database URL from FLY_PG_PROXY_CONN_STRING

## Related Issues
- #12 (Create auth service scaffold)

Red Flags

Signs of poor issue quality that need revision:

Title problems:

• Includes type prefix (feat:, bug:, etc.)
• Uses brackets like [BUG] or [FEATURE]
• Too vague ("Fix issue", "Update code")
• Describes solution instead of problem ("Use async/await")
• Contains emojis

Body problems:

• No reproduction steps for bugs
• No acceptance criteria
• Missing context for why this matters
• Wall of text without structure
• No environment details for bugs

Scope problems:

• Combines multiple unrelated changes
• Too large to complete in one PR
• Dependencies not identified

Key Principles

1. Describe problems, not solutions - The title should say what's wrong or needed, not how to fix it

2. One issue, one concern - Each issue should track a single piece of work

3. Include reproduction steps - For bugs, always include steps to reproduce

4. Define "done" - Acceptance criteria tell you when the issue is complete

5. Use labels consistently - Labels enable filtering and help with planning

6. Link related issues - Connect issues that depend on or relate to each other

7. Keep it actionable - Someone should be able to pick up the issue and start working

Integration with Workflow

Issues connect to other parts of the development workflow:

• Issue describes the problem/need
• Branch named after issue (

  feature/123-add-notifications

  )
• Commits describe solutions (conventional commits:

  feat:

  ,

  fix:

  )
• PR links back to issue (

  Closes #123

  )
• Issue closed when PR merges

This creates full traceability from problem to solution.