Skip to content
Classic documentation
  • There are no suggestions because the search field is empty.

Branching standards & best practices

Learn what branching standards are and which best practices you should use whilst developing

The added value of the branching feature is that small changes can, in theory, be released to production more quickly. However, it also introduces the risk of merge conflicts, which can be difficult and time-consuming to resolve — especially when multiple branches are active simultaneously. This document outlines the best practices designed to ensure quality, facilitate collaboration, and minimize integration issues.

Prerequisites

  • Betty Blocks has to toggle the feature flag on the organization level to enable the creation and use of branches. After the feature has been enabled, the “Create branch” button is available in the UI at the lowest sandbox:

Way of working (WoW) – General guidelines

1. Use branches for significant or isolated work

  • Create a branch when working on:
    • A major feature or module
    • Bug fixes requiring isolated testing
    • Experiments or prototypes that shouldn't affect the main app
  • Avoid unnecessary branching for tiny UI tweaks — use the main line unless team policy dictates otherwise.

2. Team collaboration

  • If building with multiple developers and/or in different branches at the same time, make clear agreements about who will work on what to avoid overlapping work on the same module. Especially keep in mind the functionality that is set up generically. 
  • Keep communicating with other developers or teams while working in different branches.
  • Optional: assign one person as “chef merge” who will take ownership of (or just supervise) the process of merging and updating branches.

3. Manage permissions

  • Limit who can create, merge, or delete branches to prevent unauthorized or accidental changes to the upper sandboxes. These permissions can be set at the organizational level in My BB.

4. Use clear and descriptive names

  • Name branches clearly to reflect the feature or purpose.
  • Clearly name and scope variables and models to avoid naming collisions.

5. Merge early and often

  • Aim to update and merge the latest changes from and to the sandbox regularly, preferably each day or within a few days to a week.
  • This minimizes merge conflicts and surprises during final integration.

6. Write clear merge titles and descriptions

  • Make a concise and focused merge description by mentioning meaningful features or fixes. Alternatively, or in addition, mention the Jira ticket IDs for referencing purposes.
  • Example 1: 
    * Feat: add file upload for importing accounts
    * Feat: add form for manually adding accounts
    * Fix: upload issue profile picture for my account
  • Example 2: 
    * PFR-1058
    * PFR-1059
    * TECHSUP-10408

7. Ensure peer review passes

  • Perform functional testing and peer review (if available) before merging.
  • Only merge if all checks pass.
    • Always double-check if the merge was successful!
  • Test after merges to ensure UI logic and data flows still work correctly in the upper sandbox.

9. Avoid long-lived branches

  • Delete branches that have been merged or are no longer needed to keep the workspace tidy.
    • It will soon be possible to copy test data from one sandbox or branch to another.
  • Reduces confusion and prevents accidental work on old branches.

10. Use feature toggles for incomplete work

  • If a feature is not fully ready but must be merged, wrap it in a feature flag.  Use a Conditional component in case of a UI element and a Condition step in case of an (scheduled) action.
  • This enables safe deployment while continuing development.

 

Types of conflicts

  • Errors that can be resolved within the merge overview
    • “Item already modified”
    • For example, if you change the name of a page that has already been changed in another branch.
  • Errors that can not be resolved within the merge overview and should be resolved manually within the branch itself
    • “<...> already taken”
    • 'cached_full_path' already taken - two pages with the same URL.
      • 'name' already taken - two data models/configurations/public files/authentication profiles/ created with the same name.
    • “Deleted item used”
      • For example, if you change anything on a page or action that has already been deleted in another branch.

 

Known limitations

  • Custom application functions do not work after updating the branch
    • There are two possible workarounds:
      • Use only one feature branch to push the custom applications to.
      • Publish your custom application functions to the block store first and then install them in your application.
  • Changes to the same action or page are not being detected if they do not directly interfere with each other, resulting in all changes being merged “randomly” together and possibly causing unexpected behavior.
    • Product has a ticket on the roadmap to show a warning when the same action or page has been changed. Our vision is that it should still be possible to edit the same action or page if they do not interfere.
  • After doing a rollback of the lowest sandbox, you are not able to merge these changes back into the branch.
    • Steps to reproduce: 
      • In branch A, create a page with a Form and merge it to the sandbox.
      • Update branch B with those changes.
      • Now, delete that Form in branch A and merge it to the sandbox again. 
      • Perform a rollback in the sandbox to go back to the previous version where you have the component again.
      • Open the update overview to get that change from the sandbox to branch A. The update overview is empty. As a result, the branch will be out of sync forever and can only be deleted.