Mixxx Integration Branch Configuration

Last updated: 2026-01-30 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.
• Uncommitted changes MUST be stashed before starting integration: git stash push -m "WIP before integration"
• Upstream MUST be fetched before integration: git fetch upstream
• The batch branch update process MUST be run before integration: ./update-branches.sh
• The integration branch MUST be checked out before merging
• Upstream main SHOULD be merged (not rebased) to preserve integration history: git merge upstream/main
• Each [x] marked branch MUST be merged to integration: git merge origin/feature/branch-name
• Stashed changes MAY be restored after integration: git stash pop
• 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
• When merging to integration, merge conflicts MUST be resolved carefully; common issues:
  • Schema revisions (increment version numbers)
  • Enum IDs in trackmodel.h (assign unique IDs)
  • Header declarations vs implementations (keep both sides' additions)
• The integration branch MUST be verified to build successfully: cmake --build build --parallel
• Basic functionality SHOULD be tested after build
• 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.

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: 3 need attention, 11 awaiting review, 1 merged upstream, 7 local-only

• Needs Attention (CHANGES_REQUESTED)
  • feature/2025.11nov.04-controller-wizard-quick-access - #15577
    • Issue: #12262
    • Created: 2025-11-04, Last comment: none, Rebased: 2026-01-30, Updated: 2026-01-30
    • Next: Check PR for specific review feedback
  • feature/2025.10oct.21-stacked-overview-waveform - #15516
    • Issue: #13265
    • Created: 2025-10-21, Last comment: 2025-10-21, Rebased: 2026-01-30, Updated: 2026-01-30
    • Next: Remove redundant HSV and LMH renderers (ronso0 feedback)
  • feature/2025.10oct.20-restore-last-library-selection - #15460
    • Issue: #10125
    • Created: 2025-10-08, Last comment: 2025-11-14, Rebased: 2026-01-30, Updated: 2026-01-30
    • Next: Separate bugfix commits with explanations (ronso0 feedback)
• Open PRs (REVIEW_REQUIRED)
  • feature/2025.11nov.05-hide-unenabled-controllers - #15580
    • Issue: #14275
    • Created: 2025-11-05, Last comment: none, Rebased: 2026-01-30, Updated: 2026-01-30
    • Next: Await review
  • feature/2025.11nov.05-waveform-cache-size-format - #15578
    • Issue: #14874
    • Created: 2025-11-06, Last comment: 2025-11-05, Rebased: 2026-01-30, Updated: 2026-01-30
    • Next: Await review
  • bugfix/2025.11nov.04-reloop-shift-jog-seek - #15575
    • Issue: #12334
    • Created: 2025-11-04, Last comment: none, Rebased: 2026-01-30, Updated: 2026-01-30
    • Next: Await review
  • 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: Await review
  • 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
  • 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
  • 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, await review
  • 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
  • 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
  • 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
  • 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: Merge to integration, await review
• 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
  • draft/2025.10oct.21-tracker-module-stems
    • Created: 2025-10-21, Rebased: none, Updated: 2025-10-21
    • Next: Continue development or archive
  • 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
• 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

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 process SHOULD be run

Example script (run from any worktree):

git fetch upstream
for dir in ~/src/mixxx-dev/*/; do
  echo "=== Updating $dir ==="
  (cd "$dir" && git rebase upstream/main && git push --force-with-lease origin HEAD) || echo "FAILED: $dir"
done

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