Merge pull request #1804 from dandi/enh-git-bug

Add git-bug distributed issue tracking

Author: yarikoptic

.github/workflows/sync-git-bug.yml

@@ -0,0 +1,50 @@
+---
+name: Sync git-bug issues
+
+on:
+  schedule:
+    # Run hourly at minute 17 (avoid top-of-hour contention)
+    - cron: "17 * * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Fetch git-bug refs so we can push incremental updates
+          fetch-depth: 0
+
+      - name: Fetch existing bug refs
+        run: |
+          git fetch origin 'refs/bugs/*:refs/bugs/*' || true
+
+      - name: Install git-bug
+        run: |
+          curl -sL -o /usr/local/bin/git-bug \
+            https://github.com/git-bug/git-bug/releases/download/v0.10.1/git-bug_linux_amd64
+          chmod +x /usr/local/bin/git-bug
+          git-bug version
+
+      - name: Configure bridge
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git-bug bridge configure \
+            --name=github \
+            --target=github \
+            --owner=dandi \
+            --project=dandi-cli \
+            --token="$GH_TOKEN"
+
+      - name: Pull issues from GitHub
+        run: git-bug bridge pull github
+
+      - name: Push bug refs to origin
+        run: |
+          git push origin 'refs/bugs/*:refs/bugs/*'

CLAUDE.md

@@ -35,3 +35,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Documentation
 - Keep docstrings updated when changing function signatures
 - CLI help text should be clear and include examples where appropriate
+
+## Issue Tracking with git-bug
+This project has GitHub issues synced locally via git-bug.  Use these commands
+to get issue context without needing GitHub API access:
+- `git bug ls status:open` - list open issues
+- `git bug show <id-prefix>` - show issue details and comments
+- `git bug ls "title:keyword"` - search issues by title
+- `git bug ls "label:bug"` - filter by label
+- `git bug bridge pull` - sync latest issues from GitHub
+
+When working on a bug fix or feature, check `git bug ls` for related issues
+to understand context and prior discussion.

DEVELOPMENT.md

@@ -132,6 +132,73 @@ view code coverage information as follows:
    lines based on whether they are covered by tests or not.
 
 
+## Git-bug: Local Issue Tracking
+
+This project uses [git-bug](https://github.com/git-bug/git-bug) for distributed,
+offline-first issue tracking.  Issues from GitHub are synced and stored as native
+git objects under `refs/bugs/*`, so you can browse and search them without internet
+access or GitHub API calls.
+
+### Installation
+
+Install git-bug from [releases](https://github.com/git-bug/git-bug/releases)
+or via a package manager:
+
+    # macOS/Linux (Homebrew)
+    brew install git-bug
+
+    # Nix
+    nix profile install nixpkgs#git-bug
+
+    # Binary download (Linux amd64)
+    curl -L -o git-bug \
+        https://github.com/git-bug/git-bug/releases/latest/download/git-bug_linux_amd64
+    chmod +x git-bug && mv git-bug ~/.local/bin/
+
+### Fetching Issues
+
+After cloning, fetch the bug refs to get local issues:
+
+    git bug pull
+
+### Quick Reference
+
+    # List open issues
+    git bug ls status:open
+
+    # Show a specific issue (by ID prefix)
+    git bug show <id-prefix>
+
+    # Search issues by title keyword
+    git bug ls status:open "title:upload"
+
+    # Filter by label
+    git bug ls "label:bug"
+
+    # Filter by author
+    git bug ls "author:username"
+
+    # Newest first
+    git bug ls status:open sort:creation-desc
+
+### Syncing with GitHub
+
+    # Pull latest issues from GitHub
+    git bug bridge pull
+
+    # Push local bug refs to remote (for team access)
+    git bug push origin
+
+### Known Limitations
+
+- **Images/media**: Bridge importers preserve image URLs as markdown text but
+  do not download image blobs.  Images hosted on
+  `user-images.githubusercontent.com` are accessible only while GitHub hosts
+  them.
+- **Two-way sync**: While git-bug supports pushing changes back to GitHub,
+  the primary workflow is pull-from-GitHub for offline access.
+
+
 ## Releasing with GitHub Actions, auto, and pull requests
 
 New releases of dandi-cli are created via a GitHub Actions workflow built