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.
• 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

Workflow

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 (weekly-ish, or 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.