86 lines
2.1 KiB
Markdown
86 lines
2.1 KiB
Markdown
# docs/issues - Issue Specification Files
|
|
|
|
This directory contains markdown files that are automatically converted to GitHub Issues when merged to `main` or `development`.
|
|
|
|
## How It Works
|
|
|
|
1. **Create a markdown file** in this directory using the template format
|
|
2. **Add YAML frontmatter** with issue metadata (title, labels, priority, etc.)
|
|
3. **Merge to main/development** - the `docs-to-issues.yml` workflow runs
|
|
4. **GitHub Issue is created** with your specified metadata
|
|
5. **File is moved** to `docs/issues/created/` to prevent duplicates
|
|
|
|
## Quick Start
|
|
|
|
Copy `_TEMPLATE.md` and fill in your issue details:
|
|
|
|
```yaml
|
|
---
|
|
title: "My New Issue"
|
|
labels:
|
|
- feature
|
|
- backend
|
|
priority: medium
|
|
---
|
|
|
|
# My New Issue
|
|
|
|
Description of the issue...
|
|
```
|
|
|
|
## Frontmatter Fields
|
|
|
|
| Field | Required | Description |
|
|
|-------|----------|-------------|
|
|
| `title` | Yes* | Issue title (*or uses first H1 as fallback) |
|
|
| `labels` | No | Array of labels to apply |
|
|
| `priority` | No | `critical`, `high`, `medium`, `low` |
|
|
| `milestone` | No | Milestone name |
|
|
| `assignees` | No | Array of GitHub usernames |
|
|
| `parent_issue` | No | Parent issue number for linking |
|
|
| `create_sub_issues` | No | If `true`, each `## Section` becomes a sub-issue |
|
|
|
|
## Sub-Issues
|
|
|
|
To create multiple related issues from one file, set `create_sub_issues: true`:
|
|
|
|
```yaml
|
|
---
|
|
title: "Main Testing Issue"
|
|
labels: [testing]
|
|
create_sub_issues: true
|
|
---
|
|
|
|
# Main Testing Issue
|
|
|
|
Overview content for the parent issue.
|
|
|
|
## Unit Testing
|
|
|
|
This section becomes a separate issue.
|
|
|
|
## Integration Testing
|
|
|
|
This section becomes another separate issue.
|
|
```
|
|
|
|
## Manual Trigger
|
|
|
|
You can manually run the workflow with:
|
|
|
|
```bash
|
|
# Dry run (no issues created)
|
|
gh workflow run docs-to-issues.yml -f dry_run=true
|
|
|
|
# Process specific file
|
|
gh workflow run docs-to-issues.yml -f file_path=docs/issues/my-issue.md
|
|
```
|
|
|
|
## Labels
|
|
|
|
Labels are automatically created if they don't exist. Common labels:
|
|
|
|
- **Priority**: `critical`, `high`, `medium`, `low`
|
|
- **Type**: `feature`, `bug`, `enhancement`, `testing`, `documentation`
|
|
- **Component**: `backend`, `frontend`, `ui`, `security`, `caddy`, `database`
|