# Jira to GitHub Issues Converter

A Rust command-line tool that converts Jira CSV exports to GitHub issue markdown files compatible with the [gh-issue-generator](../01-gh-issue-generator) tool.

## Prerequisites

- [Rust](https://www.rust-lang.org/tools/install) installed (cargo, rustc)
- Basic familiarity with Jira CSV exports

## Installation

### Option 1: Build from source

1. Clone this repository
```bash
git clone https://github.com/bee8333/2ticketss.git
cd 2ticketss/00-jira-to-gh-issues
```

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

3. The executable will be in `target/release/jira-to-gh-issues`

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

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

### Option 2: Install with Cargo

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

## Exporting Issues from Jira

1. In Jira, go to the issue list view (with all filters applied)
2. Click "Export" and select "CSV (All fields)"
3. Save the CSV file

Required Jira fields:
- Summary (required)
- Issue key (required)

Recommended fields (for best results):
- Issue Type
- Priority
- Description
- Assignee
- Reporter
- Created
- Labels

## Usage

```bash
jira-to-gh-issues [OPTIONS] --input <jira_export.csv>
```

Arguments:
- `--input, -i <jira_export.csv>`: Path to the CSV file exported from Jira (required)

Options:
- `--output, -o <output_dir>`: Directory where the markdown files will be saved
- `--status, -s <status>`: Default status for the issues (draft or ready)
- `--verbose, -v`: Increase verbosity level (can be used multiple times: -v, -vv)
- `--config, -c <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 jira-to-gh-issues --input issues.csv
   
   # Set per-module log level
   RUST_LOG=jira_to_gh_issues=trace,csv=warn jira-to-gh-issues --input issues.csv
   ```

## 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. `.jira-to-gh-issues.toml` in current directory
3. `~/.jira-to-gh-issues.toml` in home directory
4. `~/.config/jira-to-gh-issues/config.toml` in XDG config directory

A default configuration file will be created at `~/.config/jira-to-gh-issues/config.toml` if none exists.

### Configuration Options

```toml
# Default output directory
output_dir = "00-jira-to-gh-issues/output"

# Default issue status (draft or ready)
default_status = "ready"

# Required fields in CSV
required_fields = ["Summary", "Issue key"]
```

### 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 custom defaults:

```bash
mkdir -p ~/.config/jira-to-gh-issues
cat > ~/.config/jira-to-gh-issues/config.toml << EOF
output_dir = "github-issues/jira-exports"
default_status = "draft"
required_fields = ["Summary", "Issue key", "Description"]
EOF
```

## Example Workflow

### 1. Export issues from Jira
```bash
# Assuming you've exported Jira issues to "sprint-backlog.csv"
```

### 2. Convert to GitHub issue format
```bash
jira-to-gh-issues --input sprint-backlog.csv --output github-issues
```

### 3. Create GitHub issues using gh-issue-generator
```bash
cd ..
gh-issue-generator --repo myuser/myrepo github-issues/20240405123045/batch.md
```

## How It Works

1. The tool reads a CSV file exported from Jira
2. For each issue in the CSV, it:
   - Extracts relevant information (title, description, labels, etc.)
   - Converts it to the GitHub issue markdown format with YAML front matter
   - Writes individual markdown files for each issue
   - Creates a batch file containing all issues
3. Output is saved in a timestamped directory to avoid overwriting previous conversions
4. An error log is generated for any issues that couldn't be processed

## Output Format

The tool generates:
1. Individual markdown files for each issue (named after the Jira issue key)
2. A batch file containing all issues in the format expected by gh-issue-generator
3. An error log file listing any processing issues

Each generated file follows the format required by the gh-issue-generator tool:

```markdown
---
title: Issue title
status: ready (or draft)
labels:
  - label1
  - label2
assignees:
  - assignee1
---

# Issue title

## Description

Issue description...

## Metadata

- **Jira Issue**: JIRA-123
- **Created**: Creation date
- **Reporter**: Reporter name
```

## Mapping Rules

| Jira Field    | GitHub Issue Field        |
|---------------|---------------------------|
| Summary       | title                     |
| Issue Type    | Converted to a label      |
| Priority      | High/Critical → priority label |
| Labels        | labels                    |
| Description   | Description section       |
| Assignee      | assignees                 |
| Reporter      | Listed in metadata        |
| Created       | Listed in metadata        |
| Issue Key     | Listed in metadata & filename |

## Troubleshooting

### CSV Import Issues
- Ensure the CSV export from Jira includes the required fields (Summary, Issue key)
- If the import fails with "Missing required columns", verify your Jira export contains these field names
- For malformed CSV files, try opening in a spreadsheet application and re-saving

### Character Encoding
- If you see corrupted characters, ensure your CSV is UTF-8 encoded
- Some Jira instances export in different encodings depending on region settings

### Large Exports
- For very large exports (1000+ issues), consider splitting into multiple files
- Processing large files may require more memory

## Limitations

- Complex Jira markup may not convert perfectly to Markdown
- Attachments from Jira issues are not transferred
- Comments are not included in the conversion

## License

MIT