212 lines
6.0 KiB
Markdown
212 lines
6.0 KiB
Markdown
# YAML Format Specification
|
|
|
|
Complete reference for GitHub issue YAML files.
|
|
|
|
## Top-Level Structure
|
|
|
|
```yaml
|
|
repository: owner/repo # REQUIRED
|
|
project: 6 # OPTIONAL - GitHub project number
|
|
|
|
defaults: # OPTIONAL - Default values for all issues
|
|
labels: [label1, label2]
|
|
milestone: "Milestone Name"
|
|
|
|
issues: # REQUIRED - Array of issue definitions
|
|
- ref: issue1
|
|
title: "Issue Title"
|
|
body: "Issue body"
|
|
- ref: issue2
|
|
# ... more issues
|
|
```
|
|
|
|
## Required Fields
|
|
|
|
### `repository`
|
|
- Format: `owner/repo` (e.g., `myorg/myapp`)
|
|
- The GitHub repository where issues will be created
|
|
|
|
### `issues`
|
|
- Array of issue objects
|
|
- At least one issue required
|
|
|
|
### Per-Issue Fields
|
|
|
|
Each issue requires:
|
|
|
|
**`ref`** (string)
|
|
- Unique identifier for this issue within the YAML file
|
|
- Used for parent-child linking via `parent_ref`
|
|
- Not sent to GitHub (internal reference only)
|
|
- Recommended: lowercase with hyphens (e.g., `parent-issue`, `login-feature`)
|
|
|
|
**`title`** (string)
|
|
- Issue title displayed on GitHub
|
|
- Keep concise (< 80 characters recommended)
|
|
- Should be outcome-focused (WHAT, not HOW)
|
|
- Examples:
|
|
- ✅ "Enable search functionality"
|
|
- ❌ "Implement SearchService class"
|
|
|
|
**`body`** (string, multiline)
|
|
- Issue description in Markdown
|
|
- Use `|` for multiline content
|
|
- Supports GitHub Flavored Markdown
|
|
|
|
## Optional Fields
|
|
|
|
### Top-Level Optional
|
|
|
|
**`project`** (integer)
|
|
- GitHub project number (not project name)
|
|
- All created issues added to this project
|
|
|
|
**`defaults`** (object)
|
|
- Default values applied to all issues
|
|
- Can be overridden per-issue
|
|
- Supported: `labels`, `milestone`
|
|
|
|
### Per-Issue Optional
|
|
|
|
**`parent_ref`** (string)
|
|
- Reference to parent issue's `ref`
|
|
- Creates parent-child relationship
|
|
- Parent issue must be defined BEFORE child in YAML
|
|
|
|
**`milestone`** (string)
|
|
- Milestone name (exact match required)
|
|
- Overrides default milestone if specified
|
|
|
|
**`labels`** (array of strings)
|
|
- Labels to apply
|
|
- Overrides default labels if specified
|
|
- Labels don't need to exist (GitHub auto-creates)
|
|
|
|
## Issue Body Format
|
|
|
|
Standard format for issue bodies:
|
|
|
|
```markdown
|
|
## Overview
|
|
Brief description of what needs to be accomplished (the outcome).
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Specific, testable criterion
|
|
- [ ] Another testable criterion
|
|
- [ ] Final criterion
|
|
|
|
## Technical Context
|
|
- Primary domain: [models/controllers involved]
|
|
- Similar pattern: [existing feature to reference]
|
|
- Integration points: [connections to other systems]
|
|
- Consider: [gotchas, constraints, or performance notes]
|
|
```
|
|
|
|
**Notes:**
|
|
- **Overview**: Outcome-focused (what users/system can do after)
|
|
- **Acceptance Criteria**: Specific, testable, observable
|
|
- **Technical Context**: Optional - add when issue involves integration, performance, security, or unfamiliar domains
|
|
|
|
## Complete Example
|
|
|
|
```yaml
|
|
repository: myorg/myapp
|
|
project: 6
|
|
|
|
defaults:
|
|
labels: [enhancement]
|
|
milestone: "v2.0"
|
|
|
|
issues:
|
|
# Parent issue
|
|
- ref: search-feature
|
|
title: "Enable search functionality"
|
|
milestone: "v2.1" # Override default
|
|
labels: [enhancement, search]
|
|
body: |
|
|
## Overview
|
|
Add full-text search to allow users to find posts and comments quickly.
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Search bar visible in header on all pages
|
|
- [ ] Results page displays matching posts and comments
|
|
- [ ] Results are paginated (20 per page)
|
|
- [ ] Search works across post titles, bodies, and comments
|
|
|
|
## Technical Context
|
|
- Primary domain: Posts, Comments models; SearchController
|
|
- Similar pattern: Existing filter functionality in app/controllers/posts_controller.rb
|
|
- Consider: PostgreSQL full-text search vs external service (start simple)
|
|
|
|
# Child issue 1
|
|
- ref: search-indexing
|
|
parent_ref: search-feature
|
|
title: "Build search indexing"
|
|
body: |
|
|
## Overview
|
|
Create database indices to support full-text search.
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Migration adds search columns to posts and comments
|
|
- [ ] Background job updates search indices on content changes
|
|
- [ ] Search query returns results in < 200ms for typical queries
|
|
|
|
## Technical Context
|
|
- Primary domain: Posts, Comments models; db/migrate
|
|
- Similar pattern: Existing index patterns in schema.rb
|
|
- Consider: Use PostgreSQL tsvector type, GIN index
|
|
|
|
# Child issue 2
|
|
- ref: search-ui
|
|
parent_ref: search-feature
|
|
title: "Build search UI"
|
|
body: |
|
|
## Overview
|
|
Create user interface for search functionality.
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Search bar component in header
|
|
- [ ] Results page shows post/comment matches with highlighting
|
|
- [ ] Pagination controls (prev/next, page numbers)
|
|
- [ ] Empty state when no results found
|
|
|
|
## Technical Context
|
|
- Primary domain: SearchController, app/views/search
|
|
- Similar pattern: Pagination in app/views/posts/index.html.erb
|
|
- Integration points: Uses search indexing from #search-indexing
|
|
```
|
|
|
|
## Title Guidelines
|
|
|
|
Titles should describe the outcome, not implementation:
|
|
|
|
**Good (outcome-focused):**
|
|
- "Enable search functionality"
|
|
- "Users can filter posts by category"
|
|
- "Support OAuth authentication"
|
|
|
|
**Bad (implementation-focused):**
|
|
- "Implement SearchService class"
|
|
- "Add filter method to PostsController"
|
|
- "Install Devise gem"
|
|
|
|
## Technical Context Guidelines
|
|
|
|
Add Technical Context section when issue involves:
|
|
- **Integration**: Multiple systems/models working together
|
|
- **Performance**: Scale requirements (>100 records, <200ms response)
|
|
- **Security**: Auth, permissions, tenant isolation
|
|
- **Background processing**: Jobs, queues, async work
|
|
- **Unfamiliar domains**: New functionality in unknown territory
|
|
|
|
Skip Technical Context for:
|
|
- Standard CRUD (add field, basic form)
|
|
- UI-only changes (text, styling, layout)
|
|
- Copying existing pattern explicitly
|
|
|
|
**Format (3-5 bullets):**
|
|
- Primary domain: Where code lives
|
|
- Similar pattern: Existing feature to reference
|
|
- Integration points: Connections to other parts
|
|
- Consider: Gotchas, constraints, performance notes
|