2ticketss/01-gh-issue-generator/README.md

# GitHub Issue Generator

A Rust command-line tool that generates GitHub issues from Markdown files. This tool parses structured Markdown files with YAML front matter and uses the GitHub CLI to create issues.

## Prerequisites

- [GitHub CLI](https://cli.github.com/) installed and authenticated
- [Rust](https://www.rust-lang.org/tools/install) installed (cargo, rustc)

## Installation

### Option 1: Build from source

1. Clone this repository
```bash
git clone https://github.com/bee8333/2ticketss.git
cd 2ticketss/01-gh-issue-generator
```

2. Build the application:
```bash
cargo build --release
```

3. The executable will be in `target/release/gh-issue-generator`

4. Optional: Add to your PATH
```bash
# Linux/macOS
cp target/release/gh-issue-generator ~/.local/bin/

# or add the following to your .bashrc or .zshrc
export PATH="$PATH:/path/to/2ticketss/01-gh-issue-generator/target/release"
```

### Option 2: Install with Cargo

If you have Rust installed, you can install directly with:
```bash
cargo install --path .
```

### GitHub CLI Authentication

Before using this tool, you must authenticate the GitHub CLI:

```bash
# Login to GitHub
gh auth login

# Verify you're authenticated
gh auth status
```

Make sure you have the appropriate scopes (repo for private repositories) during authentication.

## Usage

```bash
gh-issue-generator [OPTIONS] <input_paths>...
```

Arguments:
- `<input_paths>...`: One or more paths to Markdown files or directories containing Markdown files

Options:
- `-r, --repo <owner/repo>`: GitHub repository in format owner/repo (e.g., "octocat/Hello-World")
- `-d, --dry-run`: Run in dry-run mode (don't actually create issues)
- `-v, --verbose`: Increase verbosity level (can be used multiple times: -v, -vv)
- `-c, --config <config>`: Path to config file

### Logging Options

You can control log verbosity in two ways:

1. Using the `--verbose` flag:
   - `-v`: Debug level logging
   - `-vv`: Trace level logging

2. Using the `RUST_LOG` environment variable:
   ```bash
   # Set global log level
   RUST_LOG=debug gh-issue-generator --repo owner/repo issues/
   
   # Set per-module log level
   RUST_LOG=gh_issue_generator=trace,walkdir=warn gh-issue-generator --repo owner/repo issues/
   ```

Examples:
```bash
# Process a single Markdown file
gh-issue-generator --repo myuser/myrepo issues/feature-request.md

# Process all Markdown files in a directory
gh-issue-generator --repo myuser/myrepo issues/

# Process multiple files
gh-issue-generator --repo myuser/myrepo issues/bug-1.md issues/feature-1.md

# Dry run (don't create actual issues)
gh-issue-generator --repo myuser/myrepo --dry-run issues/

# Use a specific config file
gh-issue-generator --config my-config.toml issues/

# Use increased verbosity for troubleshooting
gh-issue-generator --repo myuser/myrepo --verbose issues/
```

## Configuration

The tool supports configuration files to store default settings. Configuration is searched in these locations (in order):

1. Path specified with `--config` option
2. `.gh-issue-generator.toml` in current directory
3. `~/.gh-issue-generator.toml` in home directory
4. `~/.config/gh-issue-generator/config.toml` in XDG config directory

A default configuration file will be created at `~/.config/gh-issue-generator/config.toml` if none exists.

### Configuration Options

```toml
# Default GitHub repository (optional)
# If specified, you can omit --repo command line option
default_repo = "myuser/myrepo"

# Report output directory (default: "report")
report_dir = "report"
```

### Creating or Editing Configuration

You can manually create or edit the configuration file, or run the tool once to create a default configuration automatically.

For example, to set a default repository:

```bash
mkdir -p ~/.config/gh-issue-generator
cat > ~/.config/gh-issue-generator/config.toml << EOF
default_repo = "myuser/myrepo"
report_dir = "github-issues/reports"
EOF
```

## Complete Workflow Examples

### Example 1: Creating Feature Requests

1. Create a feature request Markdown file:

```bash
mkdir -p issues/features
cat > issues/features/search-feature.md << 'EOF'
---
title: Implement advanced search functionality
status: ready
labels:
  - enhancement
  - search
assignees:
  - developer1
milestone: v2.0
---

## Description

We need to add advanced search capabilities to improve user experience.

## Requirements

- [ ] Support fuzzy search matching
- [ ] Allow filtering by multiple criteria
- [ ] Add search history feature

## Technical Considerations

- Consider using Elasticsearch
- Should be optimized for performance
EOF
```

2. Create the GitHub issue:

```bash
gh-issue-generator --repo myuser/myrepo issues/features/search-feature.md
```

### Example 2: Converting from Jira and Batch Creating

1. Convert Jira issues to GitHub format:

```bash
cd ../00-jira-to-gh-issues
./target/release/jira-to-gh-issues --input sprint-tickets.csv --output ../issues
cd ..
```

2. Create all issues at once:

```bash
cd 01-gh-issue-generator
./target/release/gh-issue-generator --repo myuser/myrepo ../issues/20240405123045/batch.md
```

## Markdown Format

Each Markdown file should have YAML front matter at the beginning of the file, followed by the issue description. 

The front matter must be enclosed between `---` lines and contain at least a `title` field.

### Front Matter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `title` | Yes | Issue title |
| `status` | No | Issue status: "draft" or "ready" (default: "ready") |
| `labels` | No | Array of labels to apply to the issue |
| `assignees` | No | Array of GitHub usernames to assign the issue to |
| `milestone` | No | Milestone to add the issue to |
| `project` | No | GitHub project to add the issue to |
| `parent` | No | Issue number or URL of a parent issue |

### Issue Body

The content after the front matter becomes the issue body. It can contain any Markdown formatting, including:
- Task lists
- Code blocks
- Images
- Links
- Tables
- etc.

### Example

```markdown
---
title: Add support for OAuth2 authentication
status: ready
labels:
  - enhancement
  - security
assignees:
  - octocat
milestone: v1.0
project: Project Board
parent: 42
---

## Description

We need to add support for OAuth2 authentication to improve security.

## Tasks

- [ ] Research OAuth2 providers
- [ ] Implement OAuth2 flow
- [ ] Add tests
- [ ] Update documentation

## Additional Context

This is needed for compliance with our security requirements.
```

### Draft Issues

Issues marked with `status: draft` will not be created in GitHub. They will be reported as skipped in the summary.

## Batch Files

The tool also supports processing multiple issues from a single file. This is useful for creating related issues in a single operation.

### Batch File Format

Batch files should:
1. Start with any introductory content (optional)
2. Use the delimiter `---ISSUE---` to separate individual issues
3. Each issue section must include its own YAML front matter and body

### Example Batch File

```markdown
# Sprint Planning Issues

This file contains all issues for the upcoming sprint.

---ISSUE---

---
title: Implement login feature
status: ready
labels:
  - feature
---

## Description
Add user login functionality...

---ISSUE---

---
title: Update homepage design
status: ready
labels:
  - ui
---

## Description
Refresh the homepage design...

---ISSUE---

---
title: Database migration planning
status: draft
---

## Description
Plan the database migration...
```

### Processing Batch Files

Process a batch file the same way as a regular file:

```bash
gh-issue-generator --repo myuser/myrepo sprint-planning.md
```

The tool will create each non-draft issue as a separate GitHub issue.

## Report Generation

After processing all input files, the tool creates a timestamped report directory in `report/YYYY-MM-DD-HH-MM/`. The report contains:

1. A summary.md file with details of all processed issues
2. Copies of all processed Markdown files
   - Files for successfully created issues will have a comment with the issue URL
   - Files for failed issues will have a comment with the error message

## Parent-Child Relationship

If an issue specifies a `parent` field, the tool will add a comment to the created issue linking it to the parent issue. The parent can be specified as:
- A GitHub issue number (e.g., `42`)
- A full GitHub issue URL (e.g., `https://github.com/owner/repo/issues/42`)

## Troubleshooting

### GitHub CLI Authentication Issues

If you encounter authentication issues:
```bash
# Check your GitHub CLI authentication status
gh auth status

# Re-authenticate if needed
gh auth login
```

### Permission Issues

Ensure your GitHub user has permission to create issues in the target repository.

### Rate Limiting

If you're creating many issues, you might hit GitHub's API rate limits. The tool doesn't currently implement rate limit handling, so you might need to wait before running again.

### Common Errors

| Error | Possible Solution |
|-------|------------------|
| `No such file or directory` | Check the file paths you're providing |
| `Failed to parse YAML front matter` | Ensure your YAML is properly formatted |
| `failed to fetch resource: ...` | Check your network connection and GitHub authentication |
| `Repository not found` | Verify the repository exists and you have access to it |

## Best Practices

- Use `--dry-run` to test your issue files before creating actual issues
- Organize your issue files in a logical directory structure
- Use consistent naming conventions for your issue files
- Include detailed information in your issue descriptions to minimize follow-up questions

## License

MIT 

## AI-Assisted Issue Generation

You can use agentic assistants like Claude Projects or Cursor IDE to help generate issue markdown files. Here are template prompts you can use:

### Prompt for Generating a Single Issue

```
Create a GitHub issue markdown file with YAML front matter for the following project feature:

Feature description: [your feature description]
Key requirements:
- [requirement 1]
- [requirement 2]

The issue should include:
- A clear title
- Appropriate labels (choose from: bug, enhancement, documentation, feature, refactor)
- Detailed description
- Acceptance criteria
- Any technical considerations
```

### Prompt for Generating a Batch of Related Issues

```
Create a batch file containing GitHub issues for a sprint focused on [feature area].

Include 3-5 related issues that would be needed to implement this feature area.
Each issue should have appropriate front matter with title, labels, etc.
Make sure the issues are properly separated with the ---ISSUE--- delimiter.

The issues should cover different aspects like:
- Initial implementation
- UI/UX improvements
- Testing
- Documentation
```