Skip to content

Instantly share code, notes, and snippets.

@mxmilkiib
Last active March 11, 2026 14:09
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-03-11 14:10 URL: https://gist.github.com/mxmilkiib/5fb35c401736efed47ad7d78268c80b6 RFC 2119

Overview / rules

  • Purpose: This document tracks Milkii's personal Mixxx development setup, for creating and testing feature and bugfix branches.
  • Living document: This is a living document and SHOULD be updated as the workflow evolves.
  • Dual repo: The goal is to maintain two Mixxx source instances: a main mixxx repo and a mixxx-dev repo.
  • Main sync: Both repos MUST maintain a main branch that is synced with mixxxdj/mixxx main. origin/main MUST be kept as a fast-forward mirror of upstream/main — run git push --no-verify origin main after every git fetch upstream && git merge upstream/main on main.
  • Main read-only: The main branch MUST NOT receive any local commits — not INTEGRATION.md updates, not patches, nothing. All commits go on integration or a worktree branch. Any stray commits on main MUST be removed by force-pushing the clean upstream/main tip.
  • Worktrees: The mixxx-dev repo MUST use worktrees to host individual feature/fix branches, keeping them clean for upstream PRs.
  • Integration branch: The mixxx repo MUST have an integration branch that combines multiple branches from the mixxx-dev repo.
  • Dev location: All individual branch development should be done using the mixxx-dev directory repository
  • Integration edits: mixxx can have some edits for testing purposes, but should be kept minimal
  • Clean commits: A branch in mixxx-dev MUST have clean commits before first being linked with a GitHub PR
  • Stability: This dual setup SHOULD provide consistency for a stable bleeding-edge build without interference from local development.
  • "Updating" the system: When the user asks to "update" or says the system has been updated, this MUST include all of the following post-update checks and tasks in order:
    1. Fetch upstream and check for new commits on upstream/main
    2. Check all [x] branches: for each, verify whether its commits are already present in upstream/main (git log upstream/main --oneline | grep <keyword>); if fully merged, move the entry to the "Merged to Upstream" section, remove the [x] marker, and record the merge date — do this BEFORE rebasing or rebuilding so merged branches are excluded from both
    3. Rebase all non-merged worktree branches on new upstream/main (stash any WIP first); skip branches identified as merged in step 2; clean any branches with INTEGRATION.md or other cruft commits
    4. Rebuild the integration branch: merge upstream/main then re-merge all [x] branches in order, resolving any conflicts
    5. Build the integration branch (cmake --build build --target mixxx -- -j$(nproc --ignore=2)) and verify it succeeds
    6. Check all open PRs for new review feedback (CHANGES_REQUESTED, new comments) and update INTEGRATION.md statuses accordingly
    7. Update the "Last updated" timestamp and rebuild log entry in INTEGRATION.md, commit, and sync to Gist
  • Merge process: The integration merge process MUST follow the steps in the Integration Merge Process section below.
  • Rebase hygiene: All branches SHOULD be kept up-to-date and rebased with mixxxdj/mixxx main to minimize merge conflicts, except merged branches
  • Rebase first: A branch MUST be rebased as an initial step before any new change is made to said branch
  • Incremental PRs: 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.
  • Outline currency: The integration status outline MUST reflect the state of all branches, related issues, PRs, and dates, and MUST be updated after changes are committed — PR URLs SHOULD be checked first to catch new feedback
  • Non-interactive git: Git operations MUST be non-interactive using GIT_EDITOR=true and GIT_PAGER=cat to avoid vim/editor prompts
  • Issues: Most branches MAY have related upstream issues; related issues SHOULD be listed in the outline
  • Sections: Feature and fix branches should be in the correct outline sections
  • Secondary patches: Secondary patches are small fixes that either (a) resolve a residual problem that only became visible after a larger fix landed, or (b) are a prerequisite that a main fix branch depends on. They MUST be tracked in the Secondary Patches section of the outline, with a Depends-on or Resolves-residual-from note linking them to the related primary branch
  • Secondary patch upstream: A secondary patch SHOULD be submitted upstream independently if it stands alone; if it only makes sense in context of the primary fix, it MAY be folded into that PR
  • Dates: Dates for branch creation, last PR comment, and last update MUST be recorded in the status outline
  • Standalone branches: Each feature/fix branch SHOULD work standalone without depending on other local branches (except where noted)
  • History: Feature/fix branch history MUST NOT be rewritten (no squash, no interactive rebase) without explicit permission from Milkii. "Complete" means the upstream PR has been merged or the branch has been deliberately closed. The integration branch MAY have merge commits.
  • No cherry-pick: ALWAYS use git merge to bring branches into integration, NEVER git cherry-pick — cherry-picking creates duplicate commits with different SHAs, severs the branch relationship, makes bisect/revert unreliable, and hides what is actually in the build from git log
  • Dependencies: Any fix or feature branch that relies on another local branch MUST be noted in the Branch Dependencies section
  • Local-only: Some features (UTF-8 string controls) MUST NOT be submitted to mixxxdj/mixxx upstream as they are local-only/personal use
  • PR flow: PRs SHOULD be submitted to mxmilkiib/mixxx, and Milkii will create a further PR from there to mixxxdj/mixxx.
  • Merged cleanup: Once the PR is fully merged into mixxxdj/mixxx, the branch entry MUST be moved to the "Merged to Upstream" section of the outline and its [x] marker removed, so it is excluded from future integration rebuilds.
  • Last updated: The "Last updated" date at the top of this file MUST be updated whenever this file is edited
  • Gist sync: If this file is updated, it MUST be synced to Gist: run gh gist edit 5fb35c401736efed47ad7d78268c80b6 --filename INTEGRATION.md INTEGRATION.md from ~/src/mixxx/ (--filename targets the gist file, the positional arg supplies the local content)
  • Commit messages: Commit messages must not be too verbose, and should be concise and descriptive.
  • Conflict resolution: When resolving merge conflicts — whether during rebases or integration merges — conflicts MUST be resolved and the operation continued non-interactively
  • Code quality: Code quality MUST be verified before pushing — code should be proper, straight to the point, robust, and follow Mixxx coding style
  • Push permission: Permission MUST be sought from the user before pushing commits to GitHub. Once the user has confirmed a push in a session, further pushes in that same session MAY proceed without asking again, to reduce friction.
  • Worktree pruning: When a branch is merged upstream, closed, or abandoned, its worktree MUST be removed (git worktree remove ~/src/mixxx-dev/<name>) and the local branch ref MAY be deleted. This keeps mixxx-dev/ lean and prevents update-branches.sh from wasting time on dead branches.
  • Schema exclusion: Branches that introduce database schema migrations MUST NOT be merged into the integration branch unless all schema-changing branches use compatible, non-conflicting revision numbers. Schema branches are tracked in a dedicated "Schema-Changing Branches" section of the outline.
  • Local-only backup: All local-only branches MUST be pushed to origin (mxmilkiib/mixxx) for off-machine backup, even if they will never be PRed upstream. All worktrees share a single .git directory — losing it means losing every unpushed branch.
  • LOCAL_ONLY dependency chains: When rebasing branches that form a LOCAL_ONLY dependency chain, the dependency root MUST be rebased first, then each dependent in topological order. If the root bitrots or conflicts, all dependents are broken until the root is fixed.
  • update-branches.sh: The update-branches.sh script MUST exist as a committed file in the integration branch (not embedded in INTEGRATION.md). It MUST skip worktrees whose branches have been merged upstream, closed, or abandoned.

Worktree Branch Hygiene

CRITICAL: mixxx-dev/ worktrees MUST only contain commits belonging to their named feature.

  • NEVER commit INTEGRATION.md, integration merge commits, or unrelated fixups into a feature worktree
  • INTEGRATION.md MUST NOT be committed to any feature branch in mixxx-dev/
  • Before making any edit in mixxx-dev/, confirm the active worktree matches the intended branch:
    git -C ~/src/mixxx-dev/<worktree>/ branch --show-current
  • To verify a worktree is clean (only its own commits ahead of upstream/main):
    git -C ~/src/mixxx-dev/<worktree>/ log --oneline upstream/main..HEAD
  • If a worktree has accumulated cruft, reset it:
    • No real feature commits yet: git reset --hard upstream/main
    • Has real commits mixed with cruft: rebase only the feature commits onto upstream/main, then force-update the branch ref

Preventing Cross-Branch Contamination

  • ALWAYS create new feature branches from upstream/main, never from local main — local main may have INTEGRATION.md commits or other local-only changes that will appear as extraneous commits in any upstream PR:
    git fetch upstream
    git worktree add ~/src/mixxx-dev/<name> -b feature/<branch-name> upstream/main
  • Before committing WIP in any worktree, verify the branch is correct AND that the diff contains only changes belonging to that feature:
    git -C ~/src/mixxx-dev/<worktree>/ diff --stat
    git -C ~/src/mixxx-dev/<worktree>/ branch --show-current
  • If WIP from another feature is present in a worktree, stash it before committing:
    git -C ~/src/mixxx-dev/<worktree>/ stash push --include-untracked -m "<description of what it is and where it belongs>"
  • Before opening or updating a PR, verify the branch contains only its own commits relative to upstream/main (not local main):
    git log --oneline feature/<branch-name> --not upstream/main

Directory Structure

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

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.

Branch and Integration Status Outline

Summary: 3 need attention, 14 awaiting review, 2 schema-excluded, 7 merged upstream, 8 local-only, 1 secondary patch

Integration rebuilt 2026-02-19: applied waveform FBO + openglwindow resize fixes; fixed hotcue-labelling merge (missing setLabel/slotHotcueLabelChangeRequest); merged midi-makeinputhandler-null-engine bugfix (was missing, caused SIGSEGV/SIGABRT on controller shutdown) Integration rebuilt 2026-02-19 (second time): removed hotcue-count and catalogue-number branches — both require schema changes (v41, v42) that caused a cross-thread SQLite crash (SIGSEGV in BaseTrackCache::updateIndexWithQuery via Qt::DirectConnection on engine thread). Schema kept at upstream v40. Integration patched 2026-02-19: midi-makeinputhandler-null-engine fix was missing from the rebuild — caused repeated SIGSEGV/SIGABRT on controller shutdown (MidiControllerJSProxy::makeInputHandler null shared_ptr). Re-merged. Wayland root cause identified 2026-02-19: QOpenGLWindow subsurface resize blocks on compositor buffer realloc; workaround QT_QPA_PLATFORM=xcb XCB resize gap 2026-02-19: WA_PaintOnScreen approach abandoned — WGLWidget lacks paintEngine(), causes heap corruption abort; gap is inherent to QOpenGLWindow+createWindowContainer Integration updated 2026-02-20: added controlpickermenu-quickfx-deck-offset (#16019), fix-learning-wizard-from-prefs-button; fixed hotcue-labelling missing setLabel/slotHotcueLabelChangeRequest; build clean Integration updated 2026-02-21: merged simple-waveform-top-and-overview (Simple to top of main waveform list; Simple overview type) Integration updated 2026-02-21 (2): added Layered (LMH tail-to-tail) and Stems (stem channels) as main waveform types; build clean Integration updated 2026-02-21 (3): added CQT spectrogram main waveform type (frequency-band heatmap, showcqt-style hue mapping); build clean Integration updated 2026-02-21 (4): added Layered RGB (RGB colours, tail-to-tail); fixed CQT missing from mixxx-lib CMake target; build clean Integration patched 2026-02-21 (5): added hid-init-race-on-enumeration secondary patch (explicit hid_init() before hid_enumerate prevents concurrent re-init crash from background descriptor fetch threads); WaveformRendererCQT zero visualIncrementPerPixel guard Integration rebuilt 2026-02-28: rebased all branches on upstream/main (new upstream commits include stems model crash fix, MK2 LUT fixes, ringbuffer memory leak fix); resolved merge conflicts in waveformoverviewrenderer.cpp (StackedRGB vs Simple waveform ordering); added missing m_options member variables to waveformrendererfiltered.cpp and waveformrendererhsv.cpp; build clean Integration patched 2026-02-23: re-merged controller-wizard-quick-access (clazy range-loop-detach fix — std::as_const on all range-for loops over Qt containers); build clean Integration rebuilt 2026-03-11: rebased all branches on upstream/main (198 new upstream commits: fivefourths/fourfifths merged upstream as #16026, rating controls #15764, tuning field, BPM lock, key comparison effect, TS definitions); fivefourths and controlpickermenu-quickfx-deck-offset moved to Merged to Upstream; added waveform-menu-order (#16046); resolved conflicts in overviewtype.h + waveformoverviewrenderer.cpp/h + woverview.cpp (StackedRGB+Simple coexistence), dlgprefwaveform.cpp (moveWaveformTypeToIndex), cuecontrol.cpp/h (setLabel+slotHotcueLabelChangeRequest), dlgprefcontroller.h (showLearningWizard); build clean

  • 🔴 Needs Attention (CHANGES_REQUESTED)
    • feature/2025.11nov.04-controller-wizard-quick-access - #15577 — feedback addressed Feb 18 + fix-learning-wizard folded in Feb 22; awaiting re-review
    • feature/2025.10oct.21-stacked-overview-waveform - #15516 — old feedback addressed, unstaled Feb 17; awaiting re-review
    • feature/2025.10oct.20-restore-last-library-selection - #15460 — Reloop JS + clang-format fixed Feb 28, pushed; awaiting re-review
    • feature/2025.11nov.05-hide-unenabled-controllers - #15580 — ronso0 Nov 17 feedback addressed Feb 28; awaiting re-review
  • Secondary Patches
    • bugfix/2026.02feb.21-hid-init-race-on-enumeration — LOCAL_ONLY
      • Resolves-residual-from: bugfix/2026.02feb.18-midi-makeinputhandler-null-engine
      • Created: 2026-02-21, Updated: 2026-02-21
      • Next: Evaluate for upstream PR; assess if standalone or fold into midi-makeinputhandler PR
      • Specifics:
        • hid_open() calls hid_init() lazily; multiple HidController background threads (one per device) race to call it concurrently on startup
        • hid_init() on the hidraw backend is not thread-safe — concurrent calls corrupt the udev context, crashing inside hid_enumerate
        • Fix: call hid_init() explicitly on the main thread in HidEnumerator::queryDevices() before hid_enumerate() and before any HidController objects are constructed
        • Triggered by 3+ HID devices (Launchpad Pro MK3, MPD218, BeatMix4) spawning concurrent background descriptor-fetch threads
      • Tested?: yes (crash no longer reproduced)
  • �� BUG FIXES - Open PRs (REVIEW_REQUIRED)
    • bugfix/2026.02feb.20-controlpickermenu-quickfx-deck-offsetRESOLVED 2026-03-11 — ronso0's fix #16019 merged to main
      • Issue: #16017
      • Created: 2026-02-20, Closed: 2026-03-11
      • Fix merged upstream as #16019 by ronso0
    • bugfix/2026.02feb.20-fix-learning-wizard-from-prefs-button - #16018 CLOSED 2026-02-28
      • Created: 2026-02-20, Closed: 2026-02-28
      • Fix folded into #15577 (commit ffc28f8); bug only manifests in context of wizard menu changes
      • Specifics:
        • PR description's root cause is wrong: DlgControllerLearning uses Qt::Tool | Qt::WindowStaysOnTopHint — a top-level window; QWidget::hide() on a parent does NOT cascade to top-level children
        • On upstream/main the flow is correct: wizard shows, then mappingStarted() hides prefs dialog — wizard stays visible, prefs gets out of the way; this is intentional
        • ronso0 is right: not reproducible on main/2.5 because there is no bug there
        • The actual problem: controller-wizard-quick-access (#15577) refactored showLearningWizard() to add m_bPrefsDialogWasVisible and conditional mappingStarted() emission — this broke the original prefs-button path in that branch
        • Fix belongs inside #15577 as a self-correction, not as a standalone upstream PR
      • Tested?: yes
    • bugfix/2026.02feb.18-midi-makeinputhandler-null-engine - #16003 - APPROVED (daschuer Feb 23)
      • Created: 2026-02-18, Last comment: 2026-02-24 (daschuer approved), Rebased: 2026-03-11, Updated: 2026-02-24
      • Next: Approved — needs second reviewer or merge by daschuer
      • Tested?: yes
    • bugfix/2026.02feb.19-textured-waveform-fbo-resize - #16010 - REVIEW_REQUIRED
      • Created: 2026-02-19, Last comment: none, Rebased: 2026-03-11, Updated: 2026-02-19
      • Next: Await review
      • Specifics:
        • Improved: defer FBO reallocation to paintGL via m_pendingResize flag
      • Tested?: yes
    • bugfix/2026.02feb.19-openglwindow-resize-repaint - #16012 - DRAFT - REVIEW_REQUIRED
      • Created: 2026-02-19, Last comment: none, Rebased: 2026-03-11, Updated: 2026-02-19
      • Next: Await review
      • Specifics:
        • Restores m_dirty flag: defers extra paintGL+swapBuffers from resizeGL to next vsync
        • Does not fix Wayland resize lag (compositor-level issue)
      • Tested?: yes
    • bugfix/2026.02feb.19-wayland-opengl-resize-warning - #16014 - REVIEW_REQUIRED
      • Issue: #16013
      • Created: 2026-02-19, Last comment: 2026-02-24, Rebased: 2026-03-11, Updated: 2026-02-24
      • Next: Await review
      • Specifics:
        • Wayland + QOpenGLWindow subsurface resize causes synchronous compositor buffer realloc on every pixel of drag
        • Workaround: QT_QPA_PLATFORM=xcb (XWayland)
        • Adds qWarning at startup when Wayland detected with OpenGL waveforms and spinny widgets
        • References issues #16013 (slow resize) and #14492 (sticky mouse on waveform)
      • Tested?: yes
  • 🟡 NEW FEATURES - Open PRs (REVIEW_REQUIRED)
    • feature/2026.02feb.26-waveform-menu-order - #16046 - REVIEW_REQUIRED
      • Created: 2026-02-26, Last comment: 2026-02-26, Rebased: 2026-03-11, Updated: 2026-02-26
      • Next: Await review
      • Specifics:
        • Refactors Simple-move-to-top into moveWaveformTypeToIndex helper lambda
        • Reorders main waveform type list: Simple, Filtered, HSV, RGB, Stacked, VSyncTest
      • Tested?: no
    • feature/2026.02feb.20-simple-waveform-top-and-overview - #16021 - REVIEW_REQUIRED
      • Issue: #16020
      • Created: 2026-02-20, Last comment: 2026-02-21, Rebased: 2026-03-11, Updated: 2026-02-22
      • Next: Await review
      • Specifics:
        • Moves Simple to top of main waveform type combobox (after alphabetical sort)
        • Adds Simple as an overview waveform type (amplitude envelope, signal color, stereo mirrored)
        • Moves Simple to top of overview waveform combobox
        • Adds Layered (LMH bands stacked tail-to-tail) as main waveform type
        • Adds Stems (stem channels stacked tail-to-tail, __STEM__ only) as main waveform type
        • Adds CQT spectrogram main waveform type (frequency×time heatmap, showcqt-style hue: low=red, mid=green, high=blue)
        • Adds Layered RGB (RGB colours, LMH bands stacked tail-to-tail — RGB variant of Layered)
      • Tested?: no
    • feature/2025.10oct.20-restore-last-library-selection - #15460 - DRAFT - CHANGES_REQUESTED
      • Issue: #10125
      • Created: 2025-10-08, Last comment: 2026-02-26 (ronso0), Rebased: 2026-03-11, Updated: 2026-02-28
      • Next: CI failing (ronso0 Feb 26) + unrelated Reloop JS changes slipped in — fixed 2026-02-28: removed JS file from commit, cleaned commit message (had # Conflicts: lines), fixed all clang-format violations; re-request review
      • Specifics:
        • Separate commits for changes done - 4 commits with explanations
        • Store selection with debounced saves done - 3 second debounce timer
        • Use VERIFY_OR_DEBUG_ASSERT done
        • Root node crash in saveSelectionToConfig fixed
        • scheduleSelectionSave never called from clicked() fixed
        • DataRole mismatch in restoreLastSelection fixed — uses Qt::DisplayRole
        • activateDefaultSelection overwriting restore fixed — conditional fallback
        • Feature not activated on restore fixed — activate()/activateChild() called
        • Track row selection save/restore added via WTrackTableView
      • Tested?: yes
    • feature/2025.11nov.04-controller-wizard-quick-access - #15577 - CHANGES_REQUESTED
      • Issue: #12262
      • Created: 2025-11-04, Last comment: 2026-02-18, Rebased: 2026-03-11, Updated: 2026-02-22
      • Next: Awaiting re-review — ronso0 CHANGES_REQUESTED (Nov 16) addressed Feb 18; fix-learning-wizard folded in Feb 22 (ffc28f8)
      • Specifics:
        • devicesChanged not updating menu post-startup fixed — connected to mappingApplied
        • range-for style on m_controllerPages done
        • fix-learning-wizard folded in: emit mappingStarted() before show() so prefs dialog hides before wizard appears
      • Tested?: yes
    • feature/2025.10oct.21-stacked-overview-waveform - #15516 - DRAFT - CHANGES_REQUESTED
      • Issue: #13265
      • Created: 2025-10-21, Last comment: 2026-02-22 (mxmilkiib), Rebased: 2026-03-11, Updated: 2026-02-18
      • Next: Stale bot fired (Feb 22); our naming comment (Feb 17) + clarification (Feb 22) are latest — re-request review to unstale; no new reviewer feedback
      • Specifics:
        • Remove redundant Stacked HSV and Stacked LMH renderers done
        • Remove unnecessary static_cast done
        • Rename "Stacked (RGB)" to "Stacked" done
        • All feedback addressed
        • Left comment 2026-02-17 re: Filtered/Stacked naming confusion — see #15996
      • Tested?: yes
    • feature/2025.11nov.05-hide-unenabled-controllers - #15580 - REVIEW_REQUIRED
      • Issue: #14275
      • Created: 2025-11-05, Last comment: 2025-11-17 (ronso0), Rebased: 2026-03-11, Updated: 2026-02-28
      • Next: Awaiting re-review — ronso0 Nov 17 feedback addressed Feb 28: removed redundant null checks, confirmed rename already done
      • Specifics:
        • Rename "unenabled" to "disabled" everywhere — config keys, function names, and UI text (ronso0) done
        • Remove unnecessary null checks on tree items — always valid post-construction (ronso0) done
      • Tested?: yes
    • feature/2025.10oct.21-replace-libmodplug-with-libopenmpt - #15519 - DRAFT - REVIEW_REQUIRED
      • Issue: #9862
      • Created: 2025-10-25, Last comment: 2026-02-22 (stale-bot), Rebased: 2026-03-11, Updated: 2026-01-30
      • Next: Address daschuer architecture feedback
      • Specifics:
        • 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
        • Test fix 2026-02-19: taglibStringToEnumFileType now excludes all openmpt tracker formats (mod, s3m, xm, it, mptm, 669, amf, ams, dbm, dmf, dsm, far, mdl, med, mtm, mt2, psm, ptm, ult, umx) — none are taglib formats
      • Tested?: no
    • feature/2025.10oct.20-hotcues-on-overview-waveform - #15514 - DRAFT - REVIEW_REQUIRED
      • Issue: #14994
      • Created: 2025-10-20, Last comment: 2026-02-22 (stale-bot), Rebased: 2026-03-11, Updated: 2026-01-30
      • Next: Check recent comment, await review
      • Specifics:
        • 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
      • Tested?: no
    • feature/2025.11nov.17-deere-channel-mute-buttons - #15624 - DRAFT - REVIEW_REQUIRED
      • Issue: #15623
      • Created: 2025-11-17, Last comment: 2026-02-15, Rebased: 2026-03-11, Updated: 2026-02-15
      • Next: On hold - marked as DRAFT by ronso0
      • Specifics:
        • Marked as DRAFT by ronso0 (Feb 9)
        • daschuer (Feb 9): "mute this PR until we have demand and good plan for this turntableist feature"
        • Needs visual feedback for mute state in Mixxx
        • daschuer suggests "unmute by cue" is more accurate term than "silent cue"
        • 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
        • Needs stronger justification or pivot to the broader knob-with-kill approach
      • Tested?: yes
    • feature/2025.11nov.16-playback-position-control - #15617 - DRAFT - REVIEW_REQUIRED
      • Issue: #14288
      • Created: 2025-11-16, Last comment: 2026-02-22 (mxmilkiib), Rebased: 2026-03-11, Updated: 2026-02-09
      • Next: Await review — ronso0 confirmed no CO exists for runtime marker pos; we reopened; scope is clear
      • Specifics:
        • daschuer (Feb 9): "this feature already exists" (pref option) — clarified: pref has no CO for runtime control
        • ronso0 confirmed: if it's about changing marker pos on the fly, the pref option has no CO
        • Adds [Waveform],PlayMarkerPosition ControlPotmeter (0.0–1.0) for runtime control
      • Tested?: no
  • ⚠️ Schema-Changing Branches (Excluded from Integration)
    • feature/2025.10oct.17-library-column-hotcue-count - #15462 - REVIEW_REQUIRED
      • Issue: #15461
      • Created: 2025-10-17, Last comment: 2026-02-22 (stale-bot), Rebased: 2026-03-11, Updated: 2026-01-30
      • Next: Check recent comment, await review
      • Specifics:
        • 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
        • Removed from integration: cross-thread SQLite crash (Qt::DirectConnection cuesUpdated lambda runs updateTrackHotcueCount on engine thread)
        • Crash fixed in branch: cuesUpdated now uses AutoConnection + DB-counting overload; CueDAO::updateTrackHotcueCount(TrackId) made public
      • Tested?: no
    • feature/2025.11nov.16-catalogue-number-column - #15616 - REVIEW_REQUIRED
      • Issue: #12583
      • Created: 2025-11-16, Last comment: 2026-02-15, Rebased: 2026-03-11, Updated: 2026-02-15
      • Next: Await review
      • Specifics:
        • acolombier left review comment 2026-02-14; replied 2026-02-15
        • Schema migration revision 40 — will conflict with hotcue-count branch (also schema change)
        • Removed from integration: schema change; keeping integration at upstream schema v40 until schema branches are stable
        • Uses MusicBrainz Picard tag mapping conventions
      • Tested?: no
  • 🔵 Local Only (No PR)
    • feature/2026.02feb.17-mono-waveform-option
      • Created: 2026-02-17, Rebased: 2026-03-11, Updated: 2026-02-17
      • Next: Implement mono waveform option for main deck waveforms
      • Specifics:
        • Add option to make main deck waveforms mono (L+R muxed, top-only rendering)
        • Similar to existing overview waveform mono feature
        • Add preference checkbox in waveform settings
        • Implement mono parameter in main waveform renderers
      • Tested?: no
    • feature/2025.10oct.14-waveform-hotcue-label-options
      • Created: 2025-10-14, Rebased: 2026-03-11, 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-03-11, Updated: 2026-01-30
      • Next: Maintain for personal use (not for upstream)
    • feature/2025.09sep.25-hotcue-labelling
      • Created: 2025-09-25, Rebased: 2026-03-11, Updated: 2026-02-20
      • Next: Maintain for personal use
    • feature/2025.06jun.08-deere-deck-bg-colour
      • Created: 2025-06-08, Rebased: 2026-03-11, Updated: 2026-01-30
      • Next: Maintain for personal use
    • feature/2025.11nov.05-deere-waveform-zoom-deck-colors
      • Created: 2025-11-05, Rebased: 2026-03-11, Updated: 2026-01-30
      • Next: Merge to integration, decide if PR-worthy
      • Specifics:
        • 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
      • Specifics:
        • 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/2026.02feb.19-wglwidget-xcb-resize-gap — ABANDONED
      • Created: 2026-02-19, Updated: 2026-02-19
      • Next: Archive or delete branch
      • Specifics:
        • Attempted WA_PaintOnScreen on WGLWidget to reduce XCB resize gap
        • Abandoned: WGLWidget lacks paintEngine(), WA_PaintOnScreen causes heap corruption abort
        • Gap is inherent to QOpenGLWindow+createWindowContainer; no viable fix
  • Merged to Upstream
    • feature/2025.05may.14-fivefourths - #16026 MERGED 2026-03-11 — merged upstream as Swarnadip-Kar's PR with fourfifths + BPM lock
    • bugfix/2026.02feb.20-controlpickermenu-quickfx-deck-offset - #16019 MERGED 2026-03-11 — ronso0's fix merged to main
    • bugfix/qt6-guiprivate-missing-component RESOLVED 2026-02-19 — fixed upstream, branch deleted
    • feature/2025.11nov.05-waveform-cache-size-format - #15578 MERGED 2026-02-16
    • bugfix/2025.11nov.04-reloop-shift-jog-seek - #15575 MERGED 2026-02-15
    • bugfix/2025.11nov.16-reloop-beatmix-mk2-naming - #15615 MERGED 2026-02-11
    • bugfix/2025.11nov.04-fx-routing-persistence - #15574 MERGED 2025-11-14

TODO Summary

Needs Attention (0 branches): (none)

  • Awaiting Review (16 branches):
    • Feedback addressed, awaiting re-review: restore-last-library-selection, controller-wizard-quick-access, stacked-overview-waveform, hide-unenabled-controllers
    • Architecture changes needed: replace-libmodplug-with-libopenmpt (daschuer wants DSP moved to effect rack)
    • On hold (DRAFT): deere-channel-mute-buttons (marked draft Feb 9, needs broader plan)
    • Recent activity: hotcues-on-overview-waveform (stale Jan 19), library-column-hotcue-count (stale Jan 17)
    • Clean PRs: playback-position-control, catalogue-number-column, waveform-menu-order (#16046), midi-makeinputhandler-null-engine (approved), wayland-opengl-resize-warning, textured-waveform-fbo-resize, openglwindow-resize-repaint, simple-waveform-top-and-overview
    • Abandoned (no PR): wglwidget-xcb-resize-gap (WA_PaintOnScreen causes heap corruption; gap is inherent)
  • Secondary Patches (1 branch):
    • Evaluate for upstream: hid-init-race-on-enumeration (standalone fix or fold into midi-makeinputhandler PR)
  • Local Development (2 branches):
    • Decide PR-worthiness: deere-waveform-zoom-deck-colors
    • Continue or archive: tracker-module-stems

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 — integration branch MUST be rebuilt after any branch is added or cherry-picked:

    Incremental rebuild (most common — after source changes):

    cmake --build /home/milkii/src/mixxx/build --target mixxx -- -j$(nproc --ignore=2)

    Full reconfigure (only needed when new branches add CMakeLists changes or new source files):

    cmake -B /home/milkii/src/mixxx/build -S /home/milkii/src/mixxx -DCMAKE_BUILD_TYPE=RelWithDebInfo
    cmake --build /home/milkii/src/mixxx/build --target mixxx -- -j$(nproc --ignore=2)

    Basic functionality SHOULD be tested after build.

  10. Sync to Gist (if INTEGRATION.md was updated):

    gh gist edit 5fb35c401736efed47ad7d78268c80b6 --filename INTEGRATION.md INTEGRATION.md

Checking PR Status

gh pr view <PR-number>
gh pr list --repo mixxxdj/mixxx --author mxmilkiib

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) - STATUS
  - 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
  - Specifics:
    - Details about the branch and what probably should happen next
  • [x] = merged to integration, [ ] = not merged
  • Branch name in bold
  • 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)
  • STATUS is one of: DRAFT, REVIEW_REQUIRED, CHANGES_REQUESTED, MERGED, LOCAL_ONLY
  • Secondary patch entries use Resolves-residual-from or Depends-on instead of Issue to link to the primary branch

Section Order

  1. Needs Attention (CHANGES_REQUESTED)
  2. Secondary Patches
  3. Open PRs (REVIEW_REQUIRED)
  4. Schema-Changing Branches (Excluded from Integration)
  5. Local Only (No PR)
  6. 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 need attention, Y awaiting review, Z schema-excluded, W merged upstream, V local-only, U secondary patch
#!/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