Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

Ticketr Examples

This directory contains template files demonstrating the canonical # TICKET: schema for various use cases.

Available Templates

Quick Start Template

File: quick-story.md Purpose: Basic ticket template for simple stories or tasks When to use:

  • Creating standalone stories
  • Simple bug reports
  • Quick tasks without complex hierarchy

Key features:

  • Minimal required fields
  • Clean structure
  • Easy to customize

Epic Template

File: epic-template.md Purpose: Large initiatives with multiple child stories/tasks When to use:

  • Planning major features spanning multiple sprints
  • Organizing related work items
  • Managing complex projects

Key features:

  • Epic-level metadata
  • Child ticket organization
  • Hierarchical structure

Sprint Template

File: sprint-template.md Purpose: Sprint planning with multiple tickets When to use:

  • Planning sprint backlogs
  • Organizing iteration work
  • Batch ticket creation

Key features:

  • Multiple tickets in one file
  • Sprint-level organization
  • Consistent formatting

Pull with Subtasks Example

File: pull-with-subtasks-example.md Purpose: Demonstrates pulling tickets with subtasks from Jira using JQL queries When to use:

  • Understanding how subtasks appear in pulled Markdown files
  • Learning round-trip workflow (pull → edit → push → pull)
  • Working with hierarchical ticket structures

Key features:

  • Subtask structure in Markdown output
  • Field values for parent tickets and subtasks
  • Round-trip workflow demonstration
  • Common use cases (sprint planning, epic management, team review)
  • Technical notes on field mapping and error handling

Using These Templates

1. Copy the Template

cp examples/quick-story.md tickets/PROJ-123.md

2. Customize the Content

Edit the file to match your specific requirements:

  • Update ticket ID (e.g., PROJ-123)
  • Add description and acceptance criteria
  • Set issue type, status, assignee
  • Add tasks or subtasks as needed

3. Validate the Ticket

  • Validate with ticketr push --dry-run
  • Push with ticketr push tickets/PROJ-123.md

Template Customization Guidelines

Required Fields

All templates must include:

  • # TICKET: header with ticket ID and title
  • Valid issue type (Story, Bug, Task, Epic, etc.)

Optional Fields

Customize based on your needs:

  • Description
  • Acceptance Criteria
  • Status
  • Assignee
  • Sprint
  • Epic Link
  • Story Points
  • Labels
  • Custom fields

Formatting Rules

  • Use # TICKET: (not # STORY:) for the main header
  • Use ## TASK: for child tasks
  • Use **Field Name:** for metadata fields
  • Maintain consistent indentation

Schema Reference

For complete schema specification, see:

  • docs/development/REQUIREMENTS.md - Schema requirements
  • README.md - Quick Start and Templates sections

Creating Custom Templates

To create your own templates:

  1. Start with an existing template
  2. Add/remove fields based on your workflow
  3. Test with ticketr push --dry-run
  4. Save in your project's templates directory
  5. Share with your team

Example: Custom Bug Template

# TICKET: PROJ-456 Bug title here

**Issue Type:** Bug
**Priority:** High
**Status:** Open
**Assignee:** developer@example.com

**Description:**
[Describe the bug]

**Steps to Reproduce:**
1. [Step 1]
2. [Step 2]

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens]

**Environment:**
- OS: [e.g., Ubuntu 22.04]
- Browser: [e.g., Chrome 120]
- Version: [e.g., v1.2.3]

Format Reminder

Ticketr 1.x requires # TICKET: headings. Files created before the 1.0 release that still use # STORY: must be updated manually before use.

Additional Resources

  • CLI Help: ticketr help
  • Push/Pull: ticketr push --help, ticketr pull --help