This directory contains scripts and configuration for syncing inkless with upstream Apache Kafka.

The sync process follows the Versioning Strategy:

• Uses merge commits (not rebase) for velocity
• Preserves inkless-specific features and configurations
• Creates structured commits for different types of adaptations

Start a sync session with Claude Code using the appropriate prompt:

• Main Sync → MAIN-SYNC-PROMPT.md — weekly/biweekly sync with Apache Kafka trunk
• Release Sync → RELEASE-SYNC-PROMPT.md — sync release branches with upstream patches
• Cherry-pick Sync → CHERRY-PICK-SYNC-GUIDE.md — backport inkless features from main to release branches

Context for the agent:

• Scripts are in inkless-sync/
• Session files track in-progress work in .inkless-sync/ (gitignored)
• Completed session logs are archived to inkless-sync/sessions/
• Action plans have file-by-file playbooks

• Main Sync: Regular development sync to keep up with Apache Kafka trunk
• Release Sync: When Apache releases a patch (e.g., 4.0.1) and we need to incorporate fixes into our release branch
• Cherry-pick Sync: When inkless features land on main and need to be backported to active release branches

# Sync with latest apache/kafka trunk
./inkless-sync/main-sync.sh

# Sync to the commit just before a version tag (e.g., before 4.3)
./inkless-sync/main-sync.sh --before-version 4.3

# See what would happen without making changes
./inkless-sync/main-sync.sh --dry-run

# List available upstream release tags
./inkless-sync/release-sync.sh inkless-4.0 --list-tags

# Sync inkless-4.0 to Apache Kafka 4.0.1
./inkless-sync/release-sync.sh inkless-4.0 --to-tag 4.0.1

For detailed release sync workflow, see RELEASE-SYNC-GUIDE.md.

# Check how far behind main is from upstream trunk
./inkless-sync/sync-status.sh main

# Check release branch status
./inkless-sync/sync-status.sh inkless-4.0

# Check all branches
./inkless-sync/sync-status.sh --all

Check if inkless commits from main have been cherry-picked to release branches:

# Check inkless-4.0 consistency with main
./inkless-sync/branch-consistency.sh inkless-4.0

# Show missing commits with cherry-pick commands
./inkless-sync/branch-consistency.sh inkless-4.0 --missing

# Show ALL missing commits (including old ones that were intentionally skipped)
./inkless-sync/branch-consistency.sh inkless-4.0 --missing --all

# Create inkless-4.2 from main (main must be at 4.2.0-inkless-SNAPSHOT or later)
./inkless-sync/create-release-branch.sh 4.2

# Preview what would happen
./inkless-sync/create-release-branch.sh 4.2 --dry-run

# Force creation even if version doesn't match
./inkless-sync/create-release-branch.sh 4.2 --force

After creating the branch, sync with upstream to set the release version:

./inkless-sync/release-sync.sh inkless-4.2 --to-tag 4.2.0

# Cherry-pick all missing inkless commits to inkless-4.0
./inkless-sync/cherry-pick-to-release.sh inkless-4.0

# Preview what would be cherry-picked
./inkless-sync/cherry-pick-to-release.sh inkless-4.0 --dry-run

# Cherry-pick specific commits
./inkless-sync/cherry-pick-to-release.sh inkless-4.0 abc123 def456

For detailed cherry-pick workflow, conflict resolution patterns, and session tracking, see CHERRY-PICK-SYNC-GUIDE.md.

1. Fetches upstream apache/kafka
2. Determines sync target (trunk HEAD or before-version)
3. Generates "inkless manifest" - list of files we've modified
4. Creates sync branch: sync/upstream-YYYYMMDD

1. Executes git merge from upstream
2. Categorizes conflicts:
   • Protected: Files in storage/inkless/, docs/inkless/, etc. → Use "ours"
   • Auto-resolvable: Import conflicts, trivial changes → Auto-resolve
   • Manual: Complex conflicts → Stop and ask for human help
3. Completes merge commit or reports conflicts needing attention

1. Compiles the codebase
2. Analyzes any compilation errors
3. Errors should be fixed and committed as: sync(compile): fix compilation errors

1. Runs inkless-specific tests
2. Verifies inkless features are preserved (manifest check)
3. Generates sync report

inkless-sync/
├── main-sync.sh              # Main branch sync script
├── release-sync.sh               # Release branch sync script
├── sync-status.sh                # Check sync status vs upstream
├── branch-consistency.sh         # Check cherry-pick consistency
├── create-release-branch.sh      # Create new release branches
├── cherry-pick-to-release.sh     # Cherry-pick commits to releases
├── README.md                     # This file
├── RELEASE-SYNC-GUIDE.md         # Release sync documentation
├── RELEASE-SYNC-PROMPT.md        # AI prompt for release syncs
├── CHERRY-PICK-SYNC-GUIDE.md    # Cherry-pick sync documentation
├── CHERRY-PICK-SESSION-TEMPLATE.md  # Session template for cherry-pick syncs
├── CONFLICT-RESOLUTION-STRATEGY.md     # Conflict resolution guidance
├── MAIN-SYNC-PROMPT.md                 # AI prompt for main branch syncs
├── MAIN-SYNC-SESSION-TEMPLATE.md       # Session template for main syncs
├── MAIN-SYNC-ACTION-PLAN.md            # Action plan for main syncs
├── RELEASE-SYNC-SESSION-TEMPLATE.md    # Session template for release syncs
├── RELEASE-SYNC-ACTION-PLAN.md         # Action plan for release syncs
├── sessions/                           # Committed sync session logs
│   └── SESSION-2025-11-21.md           # Example: main sync session
├── lib/
│   └── common.sh                 # Shared utility functions
└── config/
    └── protected-patterns.txt    # Files to protect during merge

During sync, a .inkless-sync/ working directory (gitignored) is created with:

.inkless-sync/
├── SESSION-YYYY-MM-DD.md         # In-progress session file (main sync)
├── RELEASE-SESSION-{branch}-{date}.md  # In-progress session file (release sync)
├── sync-info.txt                 # Sync metadata
├── manifest-files.txt            # Files modified by inkless
├── manifest-stats.txt            # Diff stats from merge base
├── conflicted-files.txt          # Files with conflicts
├── conflicts-protected.txt       # Protected file conflicts
├── conflicts-auto-resolvable.txt # Auto-resolvable conflicts
├── conflicts-manual.txt          # Conflicts needing manual resolution
├── compile-output.txt            # Compilation output
├── compile-errors.txt            # Extracted compilation errors
└── SYNC-REPORT.md               # Final sync report

After a sync completes, move the session file to inkless-sync/sessions/ for permanent record:

mv .inkless-sync/SESSION-YYYY-MM-DD.md inkless-sync/sessions/

Files matching these patterns are auto-resolved with "ours" (inkless version) during conflicts. Only truly inkless-owned files should be listed here; version files and core Kafka files with inkless modifications are intentionally excluded so they fall into manual review:

# Inkless-owned directories (safe to auto-resolve)
storage/inkless/**
docs/inkless/**
docker/inkless/**
config/inkless/**
tests/kafkatest/tests/inkless/**
.github/workflows/inkless*.yml

# Inkless test files
core/src/test/java/kafka/server/Inkless*.java

If you don't have the apache remote configured:

git remote add apache https://github.com/apache/kafka.git
git fetch apache

After sync, use these commit message prefixes:

Example:

git commit -m "sync(compile): adapt to KafkaMetricsGroup constructor change"
git commit -m "sync(test): add NoOpRemoteLogMetadataManager to test config"

If the script reports manual conflicts:

1. Check .inkless-sync/conflicts-manual.txt for the list
2. Resolve each conflict manually
3. git add <resolved-files>
4. git commit to complete the merge
5. Continue with adaptation phase

1. Check .inkless-sync/compile-errors.txt for error list
2. Fix errors in logical groups
3. Commit each group: git commit -m "sync(compile): <description>"

1. Check test output in .inkless-sync/test-*-output.txt
2. Fix failures
3. Commit: git commit -m "sync(test): <description>"

This script is designed to be run by an automated agent (e.g., Claude):

1. Agent runs ./inkless-sync/main-sync.sh
2. If manual conflicts: Agent reports to human via PR/issue
3. If compilation errors: Agent attempts fixes, commits separately
4. If test failures: Agent analyzes and fixes or reports
5. Agent creates PR with sync report

The structured commit approach makes it easy to:

• Review what changed and why
• Revert specific fixes if needed
• Understand the sync process

• Versioning Strategy
• Inkless README
• Release Sync Guide
• Cherry-pick Sync Guide
• Conflict Resolution Strategy
• Main Sync Prompt