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, so version history is not rewritable

Strategy

We rely on a main branch, always stable, always releasable.

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

Main

• main is always deployable/stable:
  • Never push straight to it.
  • Never rewrite history
• Releases are tags on the `main` branch
• 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 — merge fast.
• Long-lived (weeks–months): big features. These are the ones that need extra care so they don't rot.

Short-lived branches

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

• Try to keep branches alive for hours to a couple days. Careless long-lived branches are where merge conflicts and "it works on my branch" problems come from.
• Delete branches after merge to keep things tidy.

Long-lived branches

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

• Regularly merge main into the feature branch (at least every weekly, and whenever main changes meaningfully). Don't wait until the end to reconcile. Whoever touches the feature branch next does the merge.
• 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.
• Draft/WIP PRs opened 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.