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

Our 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 branch

Requirements:

• Default branch is named main
• main must always be kept stable/releasable:
  • Linear history is required. No squash, rebase etc.
  • Straight push is discouraged (though not totally forbidden, see below)
  • PRs must ensure a good level of completeness
• Releases are built from the main branch.Release points are tags.
• Releases are immutable (PyPi)
• 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. This kind of branch should be preferred whenever possible. Requirement are:

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

Why should core devs create branches systematically?

In our scheme, 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. That's why direct push is discouraged even for core devs. However, it will not be totally deactivated (for core devs), as it could be needed in emergency situation (hotfix). Moreover, it will allow minimal cleaning before merging, like squashing.

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.