remenoscodes · 0xheartcode · Mar 17, 2026 · Apr 7, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -15,7 +15,7 @@ Platform bridges: `gh` (GitHub), `glab` (GitLab), REST API (Gitea/Forgejo).
 
 ## Key Commands
 ```bash
-make test                           # Run all 282 tests
+make test                           # Run all 284 tests
 make install                        # Install system-wide (/usr/local)
 git issue create "title" -l bug     # Create issue with label
 git issue ls --format full          # List issues with metadata

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ Thanks for your interest in contributing! This project welcomes contributions fr
 ```bash
 git clone https://github.com/remenoscodes/git-native-issue.git
 cd git-native-issue
-make test    # Run all 282 tests
+make test    # Run all 284 tests
 ```
 
 ## Development Setup

diff --git a/ISSUE-FORMAT.md b/ISSUE-FORMAT.md
@@ -373,7 +373,8 @@ merge-trailers    = *( trailer )
 trailer          = trailer-key ": " trailer-value CRLF
 trailer-key      = "Labels" / "Assignee" / "Priority" / "Milestone" /
                    "Fixed-By" / "Release" / "Reason" / "Provider-ID" /
-                   "Title" / custom-trailer-key
+                   "Provider-Comment-ID" / "Parent-ID" / "Title" /
+                   custom-trailer-key
 custom-trailer-key = "X-" TEXT-NO-LF
 trailer-value    = TEXT-NO-LF  ; must not contain actual LF
 
@@ -820,6 +821,22 @@ Export creates provider issues from local `refs/issues/` data:
 2. Comment export: commits without trailers are treated as comments;
    commits with trailers are metadata changes (skipped)
 
+#### Cross-Platform Export
+
+When the `--cross-platform` flag is passed, export implementations
+MUST NOT skip issues with foreign `Provider-ID:` values. Instead,
+they fall through to the new-issue creation path. After the first
+cross-platform export, the issue gains a target `Provider-ID:` (e.g.,
+`github:owner/repo#42`), and subsequent exports enter normal sync mode.
+
+This enables importing from one provider (e.g., Azure DevOps) and
+exporting to another (e.g., GitHub):
+
+```
+git issue import azuredevops:org/project --state all
+git issue export github:owner/repo --cross-platform
+```
+
 ### 8.3 Round-Trip Safety
 
 The `Provider-ID:` trailer ensures:
@@ -849,10 +866,43 @@ Provider-ID: github:owner/repo#42
 
 Format: `<provider>:<identifier>`
 
-This enables:
+### 9.1 Supported Providers
+
+| Provider     | Format                                  | Example                                  |
+|--------------|-----------------------------------------|------------------------------------------|
+| GitHub       | `github:<owner>/<repo>#<number>`        | `github:myorg/myrepo#42`                 |
+| GitLab       | `gitlab:<group>/<project>#<number>`     | `gitlab:team/app#17`                     |
+| Gitea        | `gitea:<owner>/<repo>#<number>`         | `gitea:dev/api#5`                        |
+| Forgejo      | `forgejo:<owner>/<repo>#<number>`       | `forgejo:forge/core#12`                  |
+| Azure DevOps | `azuredevops:<org>/<project>#<id>`      | `azuredevops:contoso/MyProject#1234`     |
+
+Comments use `Provider-Comment-ID:` with a `#comment-<id>` suffix:
+
+```
+Provider-Comment-ID: github:owner/repo#comment-123456
+Provider-Comment-ID: azuredevops:org/project#comment-789
+```
+
+### 9.2 Parent-ID Trailer
+
+For providers with hierarchical work items (e.g., Azure DevOps Epics,
+Features, User Stories, Tasks), the `Parent-ID:` trailer records the
+parent relationship:
+
+```
+Parent-ID: azuredevops:org/project#42
+```
+
+This preserves the hierarchy from the source provider. Implementations
+MAY use this trailer to reconstruct parent-child relationships.
+
+### 9.3 Identity
+
+Provider-ID enables:
 - Round-trip import/export without duplication
 - Cross-reference between local and remote issue IDs
 - Detecting already-imported issues during subsequent imports
+- Cross-platform export (see Section 8.2)
 
 ---
 

diff --git a/README.md b/README.md
@@ -652,7 +652,7 @@ the deliverable that makes ecosystem adoption possible.
 make test
 ```
 
-282 tests: core (77), bridge (37), merge/fsck (21), QoL (22), validation (36), quality (59), edge cases (13), comment sync (8), concurrency (9).
+284 tests: core (79), bridge (37), merge/fsck (21), QoL (22), validation (36), quality (59), edge cases (13), comment sync (8), concurrency (9).
 
 ## Performance Notes
 

diff --git a/RELEASE-CHECKLIST-v1.2.1.md b/RELEASE-CHECKLIST-v1.2.1.md
@@ -0,0 +1,168 @@
+# Release Checklist for v1.2.1
+
+## ✅ Completed Steps
+
+- [x] Fixed all 10 bugs discovered during integration testing
+- [x] Updated CHANGELOG.md with v1.2.1 entry
+- [x] Created RELEASE-NOTES-v1.2.1.md
+- [x] Updated version to 1.2.1 in bin/git-issue
+- [x] Committed all changes (commit: eeba1c5)
+- [x] Created git tag v1.2.1
+- [x] Comprehensive testing: 111/111 tests passing
+
+## 🚀 Next Steps
+
+### 1. Push to GitHub
+
+```bash
+cd /Users/emersonsoares/source/remenoscodes.git-native-issue
+
+# Push commits
+git push origin main
+
+# Push tag
+git push origin v1.2.1
+```
+
+### 2. Create GitHub Release
+
+Go to: https://github.com/remenoscodes/git-native-issue/releases/new
+
+**Tag:** v1.2.1
+**Title:** v1.2.1 - Critical Bug Fixes for Gitea/Forgejo Bridge
+**Description:** Copy from RELEASE-NOTES-v1.2.1.md
+
+**Release highlights:**
+```markdown
+## 🐛 Critical Bug Fix Release
+
+v1.2.1 fixes **10 critical bugs** discovered during comprehensive integration testing.
+
+### What's Fixed
+
+- ✅ Import/export router argument passing
+- ✅ Gitea label auto-creation with smart colors
+- ✅ GitLab comment sync
+- ✅ Optional authentication for public repos
+- ✅ Better error messages
+- ✅ Dry-run mode improvements
+
+### Testing
+- **111/111 tests passing**
+- All platforms validated: GitHub, GitLab, Gitea
+
+**Recommendation:** All v1.2.0 users should upgrade immediately.
+
+[See full release notes](./RELEASE-NOTES-v1.2.1.md)
+```
+
+### 3. Update Homebrew Formula
+
+**Repository:** https://github.com/remenoscodes/homebrew-git-native-issue
+**Formula:** Formula/git-native-issue.rb
+
+**Changes needed:**
+1. Update `url` to point to v1.2.1 tarball
+2. Update `sha256` hash
+3. Update `version` to "1.2.1"
+
+**Steps:**
+```bash
+# Get the tarball SHA256
+curl -L https://github.com/remenoscodes/git-native-issue/archive/refs/tags/v1.2.1.tar.gz | shasum -a 256
+
+# Edit the formula
+cd /path/to/homebrew-git-native-issue
+edit Formula/git-native-issue.rb
+
+# Update these lines:
+  url "https://github.com/remenoscodes/git-native-issue/archive/refs/tags/v1.2.1.tar.gz"
+  sha256 "NEW_SHA256_HERE"
+  version "1.2.1"
+
+# Test the formula
+brew install --build-from-source ./Formula/git-native-issue.rb
+git issue version  # Should show 1.2.1
+
+# Commit and push
+git add Formula/git-native-issue.rb
+git commit -m "Update git-native-issue to v1.2.1
+
+Critical bug fixes:
+- Import/export router argument passing
+- Gitea label auto-creation
+- GitLab comment sync
+- Better error handling
+- Dry-run improvements
+
+Testing: 111/111 tests passing"
+
+git push origin main
+```
+
+### 4. Test Installation
+
+```bash
+# Uninstall current version
+brew uninstall git-native-issue
+
+# Update brew
+brew update
+
+# Install new version
+brew install remenoscodes/git-native-issue/git-native-issue
+
+# Verify version
+git issue version  # Should show 1.2.1
+
+# Test basic functionality
+git issue create "Test v1.2.1" -m "Testing new release"
+git issue ls
+```
+
+### 5. Announce Release
+
+**Platforms to announce on:**
+- [ ] GitHub Discussions (if enabled)
+- [ ] Project README.md (update badge if showing version)
+- [ ] Social media (if applicable)
+
+**Announcement template:**
+```
+🎉 git-native-issue v1.2.1 released!
+
+Critical bug fixes for Gitea/Forgejo bridge:
+✅ 10 bugs fixed
+✅ Smart label auto-creation
+✅ Better error messages
+✅ 111/111 tests passing
+
+Upgrade: brew upgrade git-native-issue
+
+Details: https://github.com/remenoscodes/git-native-issue/releases/tag/v1.2.1
+```
+
+## 📊 Release Statistics
+
+**Version:** 1.2.1
+**Release Date:** 2026-02-09
+**Bugs Fixed:** 10
+**Files Changed:** 8 (560 insertions, 143 deletions)
+**Test Coverage:** 111/111 tests passing (100%)
+**Platforms Validated:** GitHub, GitLab, Gitea
+**Testing Duration:** ~2 hours comprehensive integration testing
+
+## 🔗 Important Links
+
+- **GitHub Repo:** https://github.com/remenoscodes/git-native-issue
+- **Homebrew Tap:** https://github.com/remenoscodes/homebrew-git-native-issue
+- **v1.2.1 Release:** https://github.com/remenoscodes/git-native-issue/releases/tag/v1.2.1
+- **Changelog:** CHANGELOG.md
+- **Release Notes:** RELEASE-NOTES-v1.2.1.md
+
+## 📝 Notes
+
+- This is a **patch release** addressing critical bugs from v1.2.0
+- **No breaking changes** - existing workflows continue to work
+- **Recommended for all users** - especially those using Gitea/Forgejo
+- Next release (v1.3.0) could focus on additional platform support or features
diff --git a/bin/git-issue-comment b/bin/git-issue-comment
@@ -12,7 +12,7 @@ usage() {
 usage: git issue comment <issue-id> -m <message>
 
 Options:
-   -m, --message <text>   Comment text (required)
+   -m, --message <text>   Comment text; use multiple times for paragraphs
    -h, --help             Show this help
 EOF
 	exit 1
@@ -42,7 +42,12 @@ do
 	case "$1" in
 		-m|--message)
 			test $# -ge 2 || { echo "error: -m requires a value" >&2; exit 1; }
-			message="$2"
+			if test -n "$message"
+			then
+				message="$(printf '%s\n\n%s' "$message" "$2")"
+			else
+				message="$2"
+			fi
 			shift 2
 			;;
 		-h|--help)

diff --git a/bin/git-issue-create b/bin/git-issue-create
@@ -12,7 +12,7 @@ usage() {
 usage: git issue create [options] <title>
 
 Options:
-   -m, --message <text>    Issue description (body)
+   -m, --message <text>    Issue description (body); use multiple times for paragraphs
    -l, --label <label>     Add a label (can be repeated)
    -a, --assignee <email>  Assign to someone
    -p, --priority <level>  Set priority (low, medium, high, critical)
@@ -34,7 +34,12 @@ do
 	case "$1" in
 		-m|--message)
 			test $# -ge 2 || { echo "error: -m requires a value" >&2; exit 1; }
-			body="$2"
+			if test -n "$body"
+			then
+				body="$(printf '%s\n\n%s' "$body" "$2")"
+			else
+				body="$2"
+			fi
 			shift 2
 			;;
 		-l|--label)

diff --git a/bin/git-issue-export b/bin/git-issue-export
@@ -10,10 +10,11 @@ usage() {
 usage: git issue export <provider> [options]
 
 Supported providers:
-   github:<owner>/<repo>        GitHub repository
-   gitlab:<group>/<project>     GitLab project
-   gitea:<owner>/<repo>         Gitea repository
-   forgejo:<owner>/<repo>       Forgejo repository
+   github:<owner>/<repo>           GitHub repository
+   gitlab:<group>/<project>        GitLab project
+   gitea:<owner>/<repo>            Gitea repository
+   forgejo:<owner>/<repo>          Forgejo repository
+   azuredevops:<org>/<project>     Azure DevOps Boards
 
 Options vary by provider. Use 'git issue export <provider> --help' for provider-specific options.
 
@@ -73,9 +74,14 @@ case "$provider" in
 	forgejo:*/*)
 		exec "$ISSUE_BIN_DIR/git-issue-export-gitea" "$@"
 		;;
+	azuredevops:*/*)
+		echo "error: Azure DevOps export is not yet implemented" >&2
+		echo "       use --cross-platform flag with another provider to export ADO-imported items" >&2
+		exit 1
+		;;
 	*)
 		echo "error: unsupported or invalid provider '$provider'" >&2
-		echo "       supported: github:<owner>/<repo>, gitlab:<owner>/<project>, gitea:<owner>/<repo>, forgejo:<owner>/<repo>" >&2
+		echo "       supported: github:<owner>/<repo>, gitlab:<owner>/<project>, gitea:<owner>/<repo>, forgejo:<owner>/<repo>, azuredevops:<org>/<project>" >&2
 		exit 1
 		;;
 esac
diff --git a/bin/git-issue-export-gitea b/bin/git-issue-export-gitea
@@ -14,6 +14,7 @@ usage: git issue export gitea:<owner>/<repo> [options]
        git issue export forgejo:<owner>/<repo> [options]
 
 Options:
+   --cross-platform  Export issues imported from other providers (e.g., Azure DevOps)
    --url <url>       Instance URL (default: https://gitea.com for gitea, https://codeberg.org for forgejo)
    --token <token>   API token (or use GITEA_TOKEN/FORGEJO_TOKEN env var)
    --dry-run         Show what would be exported without exporting
@@ -30,13 +31,18 @@ EOF
 
 provider=""
 dry_run=0
+cross_platform=0
 api_url=""
 api_token=""
 platform=""
 
 while test $# -gt 0
 do
 	case "$1" in
+		--cross-platform)
+			cross_platform=1
+			shift
+			;;
 		--url)
 			test $# -ge 2 || { echo "error: --url requires a value" >&2; exit 1; }
 			api_url="$2"
@@ -561,10 +567,14 @@ $cmt_body"
 				continue
 				;;
 			*)
-				# Foreign Provider-ID (from different source)
-				skipped=$((skipped + 1))
-				printf 'Skipped %s (imported from %s)\n' "$short_id" "$existing_pid"
-				continue
+				if test "$cross_platform" -eq 0
+				then
+					# Foreign Provider-ID — skip (default behavior)
+					skipped=$((skipped + 1))
+					printf 'Skipped %s (imported from %s)\n' "$short_id" "$existing_pid"
+					continue
+				fi
+				# --cross-platform: fall through to export as new issue
 				;;
 		esac
 	fi