tolgee-platform icon indicating copy to clipboard operation
tolgee-platform copied to clipboard
verified publisher icon tolgee

Branching PoC

Open stepan662 opened this issue 4 months ago • 1 comments

1. Problem

What is the core problem we are trying to solve? Why does this matter?

Users want to separate development from production, so when some translation is changed by developer or translator, it doesn't influcence production directly. This can be achieved by having multiple branches in one project. Users can then do changes outside the production branch and only after everything is ready they "merge" the changes into the production branch.

There will be a need for external tools/plugins to support branches (however it should be backwards compatible): JS-SDK, Figma plugin, Tolgee CLI, Android SDK?

2. Appetite

How much time do we want to spend on this?

1 cycle for PoC (probably 1 more for final result).

3. Solution

How do we imagine solving this problem?

Create branch in similar fashion as namespaces are implemented - new branch would be a copy of keys and translations and branch selection would filter only relevant keys beloning into that branch. Other features:

  • global branch selector (UI should remember which branch is user working on)
  • view of all existing branches with posibilities of merging them (+ delete, rename, etc.)
  • advanced merging UI
    • proper conflict resolution based on time of changes
    • ability to display added/removed translations
  • SDKs and plugins should have some "branch" option, to specify with which branch they should work with
  • Add branches permissions - to limit user permissions on different branches
    • Simplier solution would be just to protect some branches against changes
  • explore possibility of empty branches (branches that only contain stuff that needs to be changed)

4. Basic Drawings

What rough sketches or wireframes illustrate the concept?

Include diagrams, mockups, or simple text-based explanations (e.g., ASCII art, links to sketches, or embedded images).

5. Rabbit Holes

What are the potential complexities, unknowns, or risky areas?

  • empty branches, would just contain keys that should be changed
  • key deletion tracking
  • permissions for branches
  • automations settings for different branches (e.g. machine translation), possibilities to enable/disable some settings on different branches
  • pricing
    • maybe count number of unique keys?

6. No-Goes

What explicitly falls outside the scope of this pitch?

  • we want to avoid copying languages when creating a branch

7. Success Criteria

How will we measure success?

We want to make sure, users are able to use branching for feature branches

  • evaluate PoC with users that were interested in this feature, if we are fulfilling their criteria
  • maybe also for branches based on environment (dev, staging, prod).

stepan662 avatar Aug 08 '25 11:08 stepan662

Scopes

Branch foundation (schema + context)

  • [x] New Branch entity and table
    • [x] Add nullable branch_id to Key
  • [x] Existing APIs work as before with no branch parameter
  • [x] Simple health test passes for legacy projects
  • [x] I think I know how to do it
  • [x] I have validated my approach

Branch management (API)

  • [x] API endpoints for branch creation, listing, updating/deletion
  • [x] Deletion of a default branch is blocked
  • [x] I think I know how to do it
  • [x] I have validated my approach

Branch creation copy engine

  • [x] Service to copy Keys and Translations from a source to a target branch
    • [x] Languages, screenshots, etc. remain shared
    • [x] Copy KeyMeta and its related entities (comments, codeReferences, tags)
    • [x] Copy Translation comments
  • [x] Editing a key/translation on a new branch does not affect the default branch
  • [x] I think I know how to do it
  • [x] I have validated my approach

Branch-aware modifications

  • [x] Add optional branch context to read/write API endpoints related to Key and Translation
  • [x] All key/translation lists (Translation view) reflect the selected branch's data
  • [ ] Existing SDKs work against default branch implicitly
  • [ ] I think I know how to do it
  • [ ] I have validated my approach

UI: Global branch selector + basic merge

  • [x] Global branch selector in navbar with persistence
    • [x] All key/translation pages bind to selected branch
  • [x] Create/delete branch interface
  • [x] Merge screen to choose branches and run dry-run
  • [x] Merge screen to apply merge
  • [x] I think I know how to do it
  • [ ] I have validated my approach

Minimal merge (dry-run diff + apply)

  • [x] API endpoint for merge dry-run and apply
  • [x] Dry-run returns diff with added, removed, and modified keys
  • [x] Simple conflict policy implemented
  • [x] A conflict scenario is recognized and reported
  • [x] I think I know how to do it
  • [x] I have validated my approach

Backward compatible rollout

  • [x] New project creation creates a default Branch row
  • [x] Read fallback for existing projects (NULL as default)
  • [x] Read-repair on write: NULL branch_id is set to id of default branch
  • [ ] (Optional) Background job to backfill NULL branch_id or backfill on runtime (on feature first-time usage)
  • [ ] I think I know how to do it
  • [ ] I have validated my approach

dkrizan avatar Sep 24 '25 11:09 dkrizan

The PoC was completed, and the Branching feature is specified in this Pitch: https://github.com/tolgee/tolgee-platform/issues/3332

ZuzanaOdstrcilova avatar Dec 12 '25 09:12 ZuzanaOdstrcilova