Branching and Version Control

The purpose of this document is to define the rules for branching strategy for LuxCoreRender repositories.

Status: PROPOSAL

Preliminary considerations

A few considerations should be kept in mind:

• We are a very small core team. Branch strategy should be light and agile.
• However, we want to be able to welcome occasional contributors.
• Our needs vary depending on whether we are in feature development phases or release and stabilization phases.
• Our availability varies, which means that some development tasks may take time (and the related development branches may remain active for a long time).
• We deploy on PyPi, where releases are immutable

Strategy

The strategy is inspired by Trunk-Based Development (TBD)

We rely on a main branch, always stable, always releasable. This branch is "the Single Source of Truth" where all development happens.

main ─────●────●─────────●────●────●──→  (always stable, always releasable)
            \                   \
             feature/big-thing   feature/another-thing
              (lives for weeks,    (short, merges fast)
               synced regularly)

This applies to all LuxCoreRender repositories, and especially:

• LuxCoreDeps
• LuxCore
• BlendLuxCore

Main

Requirements:

• Default branch is named main
• main is always stable/releasable
  • Linear history is required
  • Straight push is discouraged (but not totally forbidden)
  • PRs must ensure a certain level of completeness
  • main is protected against direct push, at least from non-core developers
• Releases are tags on the main branch
• Releases are immutable
• Every piece of work gets a short- or long-lived branch: feature/login-form, fix/cart-bug, chore/upgrade-deps.

Then, two branch lifespans, both fine:

• Short-lived (hours–days): bug fixes, small features — developers required to merge fast.
• Long-lived (weeks–months): big features — developers required to give extra care to keep them alive, so they don't rot.

Short-lived branches

Short-lived branches are those which won't live more than a week. After that, they should be reclassified as long-lived branches.

• Create branch systematically, avoid direct push. See below.
• Reclassify into long-lived branch if duration exceeds week, and apply llb rules
• Delete branches after merge to keep things tidy.

Why should we create branch systematically? main must always remain stable/releasable. But with direct push, in case of CI failure, merging will not be prevented and main will be broken.

Long-lived branches

Keeping long-lived branches alive and mergeable is the actual hard problem — a branch that sits for 6 weeks while main moves on becomes a merge nightmare. A few techniques:

• Avoid long-lived branch when possible: rather use feature flags for anything mergeable in pieces. If a big feature can be built incrementally, merge the scaffolding into main early behind a flag (if FEATURE_X_ENABLED:) rather than keeping it all on a branch. This is the single best way to avoid branch drift — the branch just stops existing. GitHub, GitLab, and most large projects lean on this heavily for exactly this reason.
• Regularly merge main into the feature branch (at least once a week, and whenever main changes meaningfully). Don't wait until the end to reconcile. Whoever touches the feature branch next does the merge.
• Open Draft/WIP PRs early, even if the feature won't land for months. Gives visibility to the other maintainer and any contributors, invites early feedback before you're deep in a direction, and signals "someone's working on this" so others don't duplicate effort.