Skip to content

Instantly share code, notes, and snippets.

@mxmilkiib
Last active February 14, 2026 09:08
Show Gist options
  • Select an option

  • Save mxmilkiib/5fb35c401736efed47ad7d78268c80b6 to your computer and use it in GitHub Desktop.

Select an option

Save mxmilkiib/5fb35c401736efed47ad7d78268c80b6 to your computer and use it in GitHub Desktop.
prompt: local AI dev process; 2 repos, one individual branches, other for merging n test build

prompt: local AI dev process; 2 repos, one individual branches, other for merging n test build

INTEGRATION.md

Mixxx Integration Branch Configuration

Last updated: 2026-02-14 URL: https://gist.github.com/mxmilkiib/5fb35c401736efed47ad7d78268c80b6 RFC 2119

Overview

This document tracks Milkii's personal Mixxx development setup for the creation and testing of feature and bugfix branches. It is a living document and SHOULD be updated as the workflow evolves.

  • The goal is to maintain two Mixxx source instances: a main mixxx repo and a mixxx-dev repo.
  • Both repos MUST maintain a main branch that is synced with mixxxdj/mixxx main.
  • The mixxx-dev repo MUST use worktrees to host individual feature/fix branches, keeping them clean for upstream PRs.
  • The mixxx repo MUST have an integration branch that combines multiple branches from the mixxx-dev repo.
  • This dual setup SHOULD provide consistency for a stable bleeding-edge build without interference from local development.
  • The integration outline, i.e. the indented list below, MUST reflect the state of the various branches, related issues and PRs, and dates.
  • The integration merge process MUST follow the steps in the Integration Merge Process section below.
  • PR urls SHOULD be checked regularly for status, new feedback, and todo items
  • Related issues SHOULD be listed in the integration outline below
  • Updates to PR status MUST be reflected in the integration outline below
  • Each feature/fix branch SHOULD work standalone without depending on other local branches (except where noted)
  • New branches MUST be created with a worktree in mixxx-dev/ from the latest mixxxdj/mixxx main branch.
  • Dates for branch creation, last PR comment, and last update MUST be recorded.
  • Most branches MAY have related upstream issues.
  • If any activity changes the state of a branch, the relevant part of the integration outline MUST be updated.
  • INTEGRATION.md dates and statuses MUST be updated after changes and committed.
  • A branch MUST be rebased as an initial step before any new changes are made to the branch
  • All branches SHOULD be kept up-to-date and rebased with mixxxdj/mixxx main to minimize merge conflicts, except for local-only and merged branches
  • Feature/fix branch history MUST NOT be rewritten unless the feature/fix is complete, then ask Milkii for permission to squash/rebase; integration branch can have merge commits.
  • Changes to mixxxdj/mixxx PRs MUST be incremental so as to be easy to review, and MUST NOT completely reformulate a system in a single commit.
  • Some features (UTF-8 string controls) MUST NOT be submitted to mixxxdj/mixxx upstream as they are local-only/personal use
  • Merge conflict resolution and build verification are documented in the Integration Merge Process section below.
  • Permission MUST be sought from the user before pushing commits to GitHub.
  • PRs SHOULD be submitted to mxmilkiib/mixxx, and Milkii will create a further PR from there to mixxxdj/mixxx.
  • Once the PR is accepted into mixxxdj/mixxx, the branch MUST be removed from integration tracking.
  • If this file is updated, then it MUST be sent back to Gist by using gh.

Directory Structure

Path Purpose
~/src/mixxx/ Main repo - main and integration branches
~/src/mixxx-dev/ Development worktrees for feature/bugfix branches

Branch and Integration Status Outline

Summary: 1 needs attention, 15 awaiting review, 1 approved, 7 local-only

  • πŸ”΄ Needs Attention (CHANGES_REQUESTED)
    • feature/2025.10oct.21-replace-libmodplug-with-libopenmpt - #15519
      • Issue: #9862
      • Created: 2025-10-25, Last comment: 2025-10-25, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Address daschuer architecture feedback
      • Specific:
        • DSP in SoundSource is "foreign to Mixxx" β€” daschuer wants bit-perfect decode, move DSP to effect rack instead
        • Rename constants to kXBassBufferSize style naming (daschuer)
        • Remove VS Code minimap // MARK: comments
        • Review comments on trackerdsp.cpp and trackerdsp.h
        • Windows CI test failure (screenWillSentRawDataIfConfigured timeout) β€” may be flaky or platform-specific QImage behavior
  • 🟒 Approved (AWAITING_MERGE)
    • bugfix/2025.11nov.04-reloop-shift-jog-seek - #15575
      • Issue: #12334
      • Created: 2025-11-04, Last comment: 2026-02-09, Rebased: 2026-02-14, Updated: 2026-02-14
      • Next: Awaiting merge to 2.5 stable
      • Specific:
        • Rebased onto 2.5 stable branch per ronso0 request (mapping fix)
        • Code already uses engine.getValue(group, "track_loaded") as requested
        • Approved by ronso0 (Feb 9, 2026)
  • 🟑 Open PRs (REVIEW_REQUIRED)
    • feature/2025.11nov.04-controller-wizard-quick-access - #15577
      • Issue: #12262
      • Created: 2025-11-04, Last comment: 2025-11-16, Rebased: 2026-02-14, Updated: 2026-02-14
      • Next: Awaiting re-review from ronso0
      • Specific:
        • Changed to ControllerManager::mappingApplied signal for menu updates (Nov 16 feedback)
        • Hide menu when empty instead of disabled action (fixes Qt 6.2.3 issue)
        • Flag-based solution replaces disconnect/reconnect pattern for cleaner code
        • Suppress preferences dialog when wizard launched from menu
    • feature/2025.11nov.05-hide-unenabled-controllers - #15580
      • Issue: #14275
      • Created: 2025-11-05, Last comment: 2025-11-17, Rebased: 2026-02-14, Updated: 2026-02-14
      • Next: Awaiting re-review from ronso0
      • Specific:
        • Consistent "disabled" terminology throughout (UI text, config keys, function names)
        • Removed unnecessary null check on Controller* (ctor already asserts validity)
        • All feedback addressed
    • feature/2025.11nov.05-waveform-cache-size-format - #15578
      • Issue: #14874
      • Created: 2025-11-06, Last comment: 2026-02-14, Rebased: 2026-02-14, Updated: 2026-02-14
      • Next: Awaiting review approval
      • Specific:
        • Commits squashed into single commit (Swiftb0y request - Nov 18, 2025)
        • Changed to SI format (GB, MB, kB) with precision 1 (ronso0 feedback - Feb 10, 2026)
        • Code now uses QLocale::DataSizeSIFormat instead of IEC format
    • feature/2025.10oct.21-stacked-overview-waveform - #15516
      • Issue: #13265
      • Created: 2025-10-21, Last comment: 2025-10-21, Rebased: 2026-02-14, Updated: 2026-02-14
      • Next: Awaiting re-review from ronso0
      • Specific:
        • Removed redundant Stacked Filtered and Stacked HSV renderers (Oct 21 feedback)
        • Kept only Stacked RGB which provides unique visualization
        • Existing Filtered and HSV modes already show combined frequency view
    • feature/2025.10oct.20-restore-last-library-selection - #15460
      • Issue: #10125
      • Created: 2025-10-08, Last comment: 2025-11-14, Rebased: 2026-02-14, Updated: 2026-02-14
      • Next: Awaiting re-review from ronso0 and daschuer
      • Specific:
        • Implemented debounced save (3s delay) to balance crash resilience with performance
        • Scroll position now saved with selection state via signal
        • Uses VERIFY_OR_DEBUG_ASSERT for match() validation
        • Code organization optimized per feedback
        • Strategy: saves during session to survive crashes, not just on shutdown
    • bugfix/2025.11nov.04-reloop-shift-jog-seek - #15575
      • Issue: #12334
      • Created: 2025-11-04, Last comment: 2026-02-09, Rebased: 2026-02-14, Updated: 2026-02-14
      • Next: Approved - awaiting merge
      • Specific:
        • Rebased onto 2.5 stable branch per ronso0 request (mapping fix)
        • Code already uses engine.getValue(group, "track_loaded") as requested
        • Approved by ronso0 (Feb 9, 2026)
    • feature/2025.10oct.21-replace-libmodplug-with-libopenmpt - #15519
      • Issue: #9862
      • Created: 2025-10-25, Last comment: 2025-10-25, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Address daschuer architecture feedback
      • Specific:
        • DSP in SoundSource is "foreign to Mixxx" β€” daschuer wants bit-perfect decode, move DSP to effect rack instead
        • Rename constants to kXBassBufferSize style naming (daschuer)
        • Remove VS Code minimap // MARK: comments
        • Review comments on trackerdsp.cpp and trackerdsp.h
        • Windows CI test failure (screenWillSentRawDataIfConfigured timeout) β€” may be flaky or platform-specific QImage behavior
    • feature/2025.10oct.20-hotcues-on-overview-waveform - #15514
      • Issue: #14994
      • Created: 2025-10-20, Last comment: 2026-01-19, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Check recent comment, await review
      • Specific:
        • PR marked stale (Jan 19 2026) β€” needs activity to unstale
        • Paint hotcues on scaled image (option b) not full-width β€” scaling happens in OverviewCache so fixed pixel widths don't translate
        • Remove // MARK: comments
        • Get cue data from delegate columns instead of SQL queries (done)
        • Review feedback from ronso0 on marker rendering approach
    • feature/2025.10oct.17-library-column-hotcue-count - #15462
      • Issue: #15461
      • Created: 2025-10-17, Last comment: 2026-01-17, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Check recent comment, await review
      • Specific:
        • PR marked stale (Jan 17 2026) β€” needs activity to unstale
        • Broad discussion about whether hotcue count column is the right approach vs a "prepared" state flag (daschuer, ronso0)
        • Potential pie chart icon instead of plain number (daschuer suggestion)
        • Related to hotcues-on-overview-waveform PR #15514 (acolombier suggested rendering hotcues in overview column instead)
        • Schema change v39β†’v40 β€” will conflict with other schema changes
    • feature/2025.11nov.17-deere-channel-mute-buttons - #15624
      • Issue: #15623
      • Created: 2025-11-17, Last comment: 2025-11-20, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Merge to integration, consider broader approach
      • Specific:
        • ronso0 questions necessity β€” "Why is the Vol fader not sufficient?"
        • daschuer suggests broader approach: knob widget with integrated kill/mute feature, explore Tremolo effect for "Transformer" effect, redirect energy to alternative EQ model / stem controls discussion
        • ronso0 agrees on knob with integrated kill, right-click behavior option in Preferences > Interface
        • Needs stronger justification or pivot to the broader knob-with-kill approach
    • feature/2025.11nov.16-playback-position-control - #15617
      • Issue: #14288
      • Created: 2025-11-16, Last comment: none, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Merge to integration, await review
      • Specific:
        • No review comments yet
        • Adds [Waveform],PlayMarkerPosition ControlPotmeter (0.0–1.0)
        • Clean PR, just needs reviewer attention
    • feature/2025.11nov.16-catalogue-number-column - #15616
      • Issue: #12583
      • Created: 2025-11-16, Last comment: none, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Merge to integration, await review
      • Specific:
        • No review comments yet
        • Schema migration revision 40 β€” will conflict with hotcue-count branch (also schema change)
        • Uses MusicBrainz Picard tag mapping conventions
    • bugfix/2025.11nov.16-reloop-beatmix-mk2-naming - #15615
      • Created: 2025-11-16, Last comment: none, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Merge to integration, await review
      • Specific:
        • No review comments yet
        • Simple file rename PR, related to #12422 (MK1 support discussion)
    • feature/2025.05may.14-fivefourths - #14780
      • Issue: #14686
      • Created: 2025-05-14, Last comment: 2025-05-16, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Fix tests, update manual, merge to integration
      • Specific:
        • Fix failing tests (Swiftb0y: "Next step would be to actually get the tests to pass")
        • Update the Mixxx manual (acolombier request)
        • daschuer has no objections to the CO approach
        • Swiftb0y confirmed no performance implications from new COs
  • πŸ”΅ Local Only (No PR)
    • feature/2025.10oct.14-waveform-hotcue-label-options
      • Created: 2025-10-14, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Maintain for personal use
    • feature/2025.10oct.08-utf8-string-controls
      • Dependency for: hotcue-labelling, hotcue-label-options
      • Created: 2025-10-08, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Maintain for personal use (not for upstream)
    • feature/2025.09sep.25-hotcue-labelling
      • Created: 2025-09-25, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Maintain for personal use
    • feature/2025.06jun.08-deere-deck-bg-colour
      • Created: 2025-06-08, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Maintain for personal use
    • feature/2025.11nov.05-deere-waveform-zoom-deck-colors
      • Created: 2025-11-05, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Merge to integration, decide if PR-worthy
      • Specific:
        • Evaluate if the Deere-specific waveform zoom deck color change is worth a PR or remains personal use
        • Test visual appearance across deck configurations
    • draft/2025.10oct.21-tracker-module-stems
      • Created: 2025-10-21, Rebased: none, Updated: 2025-10-21
      • Next: Continue development or archive
      • Specific:
        • Depends on replace-libmodplug-with-libopenmpt (#15519) being accepted first
        • Adds stem support for tracker modules using libopenmpt
        • Not rebased β€” needs rebase before any work
    • bugfix/qt6-guiprivate-missing-component
      • Qt6 build fix
      • Created: unknown, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Test if still needed, submit PR or delete
      • Specific:
        • Build with Qt6 to verify if Qt6::GuiPrivate component is still missing
        • If fixed upstream, delete branch and worktree
        • If still needed, create a proper PR
  • βœ… Merged to Upstream
    • bugfix/2025.11nov.04-fx-routing-persistence - #15574
      • Issue: #14917
      • Created: 2025-11-04, Last comment: 2025-11-14, Rebased: 2026-01-30, Updated: 2026-01-30
      • Next: Delete local branch
      • Specific:
        • Run git worktree remove if worktree exists
        • Delete local branch
        • Optionally delete remote branch from mxmilkiib/mixxx

Branch Dependencies

utf8-string-controls (LOCAL_ONLY)
β”œβ”€β”€ hotcue-labelling (LOCAL_ONLY)
└── hotcue-label-options (LOCAL_ONLY)

Branches with dependencies on local-only branches cannot be submitted upstream as-is. They MUST be refactored to remove the dependency or the dependency MUST be upstreamed first.


TODO Summary

Needs Attention (3 branches):

  • controller-wizard-quick-access: Check PR for specific review feedback
  • stacked-overview-waveform: Remove redundant HSV and LMH renderers (ronso0 feedback)
  • restore-last-library-selection: Separate bugfix commits with explanations (ronso0 feedback)

Awaiting Review (8 branches):

  • hide-unenabled-controllers, waveform-cache-size-format, reloop-shift-jog-seek, replace-libmodplug-with-libopenmpt, fivefourths
  • Recent comments: hotcues-on-overview-waveform (2026-01-19), library-column-hotcue-count (2026-01-17)

Ready to Merge to Integration (5 branches):

  • deere-channel-mute-buttons, playback-position-control, catalogue-number-column, reloop-beatmix-mk2-naming, fivefourths

Local Development (3 branches):

  • Decide PR-worthiness: deere-waveform-zoom-deck-colors
  • Continue or archive: tracker-module-stems
  • Test if needed: qt6-guiprivate-missing-component

Cleanup:

  • Delete merged branch: fx-routing-persistence

Testing Checklist (Before Pushing to PR upstream)

Pre:

  • Branch rebased on latest mixxxdj/mixxx main

During:

  • Builds without errors
  • No new compiler warnings
  • Basic functionality tested

Post:

  • No regressions in related features

Batch Branch Update Process

This process updates all feature/bugfix branches in mixxx-dev/ to latest upstream:

  • Upstream MUST be fetched first (from any worktree): git fetch upstream
  • For each worktree directory in ~/src/mixxx-dev/:
    • The branch MUST be rebased on upstream/main: git rebase upstream/main
    • Conflicts MUST be resolved if any occur
    • The rebased branch SHOULD be force-pushed to origin: git push --force-with-lease origin HEAD
    • The "Rebased" date in INTEGRATION.md MUST be updated
  • Branches with unresolved conflicts SHOULD be noted for later attention
  • After all branches are updated, the Integration Merge Process SHOULD be run

Automated via ./update-branches.sh (run from ~/src/mixxx/).

Integration Merge Process

This process merges all [x] marked branches into the integration branch for a combined bleeding-edge build.

Steps

  1. Commit pending INTEGRATION.md changes (if any) before starting:
    git add INTEGRATION.md && git commit -m "update INTEGRATION.md before integration"
  2. Fetch upstream
    git fetch upstream
  3. Run batch branch update to rebase all worktree branches on upstream/main:
    ./update-branches.sh
  4. Checkout the integration branch
    git checkout integration
  5. Merge upstream/main into integration (merge, not rebase, to preserve integration history):
    git merge upstream/main
  6. Merge each [x] branch from the outline that has "Next: Merge to integration":
    git merge origin/<branch-name>
  7. Resolve merge conflicts carefully. Common issues:
    • Schema revisions: increment version numbers
    • Enum IDs in trackmodel.h: assign unique IDs
    • Header declarations vs implementations: keep both sides' additions
  8. Update INTEGRATION.md:
    • Change [ ] to [x] for newly merged branches
    • Update "Rebased" and "Updated" dates to today
    • Update the summary line counts
    • Update the "Last updated" date at the top
  9. Build and verify:
    cmake --build build --parallel
    • Basic functionality SHOULD be tested after build
  10. Sync to Gist (if INTEGRATION.md was updated):
    gh gist edit 5fb35c401736efed47ad7d78268c80b6 INTEGRATION.md

Outline Format Reference

This section documents the structure of this file for AI assistants and future maintainers.

Branch Entry Format

Branch naming convention: feature/YYYY.MMmon.DD-thing-descriptive-title

- [x] **branch-name** - [#PR](url)
  - Issue: [#ISSUE](url)
  - Optional description
  - Created: YYYY-MM-DD, Last comment: YYYY-MM-DD, Rebased: YYYY-MM-DD, Updated: YYYY-MM-DD
  - Next: Action item
  • [x] = merged to integration, [ ] = not merged
  • Branch name in bold
  • PR link if exists, omit for local-only
  • Issue link to related Mixxx issue/feature request (if applicable)
  • Created date required for all branches
  • Last comment date shows most recent PR comment ("none" if no comments), only for PRs
  • Rebased date shows when branch was last rebased on mixxxdj/mixxx main ("none" if never)
  • Updated date tracks last modification to branch
  • Next action describes what needs to be done for this branch
  • Within each section: [x] (integrated) branches first, then [ ] (not integrated) branches
  • Within each group ([x] or [ ]), sort by updated date (newest first)

Section Order

  1. Needs Attention (CHANGES_REQUESTED)
  2. Open PRs (REVIEW_REQUIRED)
  3. Local Only (No PR)
  4. Merged to Upstream

Summary Line

When updating integration: Update the "Last updated" date at the top of this file.

Update the summary line at the top when adding/removing branches:

**Summary**: X PRs need attention, Y open PRs awaiting review, Z merged upstream, W local-only branches
#!/bin/bash
# Batch update script for Mixxx development branches
# Updates all worktree branches in ~/src/mixxx-dev/ to latest upstream
set -e
echo "=== Starting batch branch update ==="
echo "Fetching upstream..."
# Fetch from main repo
git fetch upstream
echo "Updating worktree branches..."
# Update each worktree
for dir in ~/src/mixxx-dev/*/; do
if [ -d "$dir" ]; then
branch_name=$(basename "$dir")
echo "=== Updating $branch_name ==="
(
cd "$dir"
if git rebase upstream/main; then
echo "βœ… $branch_name rebased successfully"
git push --force-with-lease origin HEAD
echo "βœ… $branch_name pushed to origin"
else
echo "❌ $branch_name failed to rebase"
exit 1
fi
)
fi
done
echo "=== Batch update complete ==="
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment