Initial commit
This commit is contained in:
Zhongwei Li
211
skills/draft-github-issues/references/YAML-FORMAT.md
Normal file
211
skills/draft-github-issues/references/YAML-FORMAT.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user