Hub
Artbox
Technical Guide

Introduction

The diagram illustrates the flow of the development process. The GIMP development branch is the foundation, and the ‘convert-to-artbox’ branch serves as the common base for all feature branches. These feature branches contribute to the final ‘Artbox’ branch, which represents the integrated work from all features.

Contents

Branch Development Flow for GIMP to Artbox

graph LR;
    A([GIMP Dev])
    B([Convert to Artbox])
    C([Feature A])
    D([Feature B])
    E([Feature C])
    F([Artbox])

    A --> B
    B --> C
    B --> D
    B --> E
    C --> F
    D --> F

Diagram 4: This diagram illustrates the flow from the GIMP Dev branch to the final Artbox branch. The ‘convert-to-artbox’ branch is created from GIMP Dev, and it supports the development of multiple feature branches. Each feature branch, originates from the common ‘convert-to-artbox’ base branch. Finally, the individual feature branches merge into the ‘artbox’ branch

Updating Artbox to GIMP Dev

To keep Artbox up-to-date with the GIMP development branch, we follow a structured process divided into three main steps

Step 1: Construct the Common Base

  • Reset the Common Base: Reset the ‘convert-to-artbox’ branch to the latest commit from the GIMP master branch.
  • Rebase the Convert Branches: Rebase the convert branches to the GIMP master branch.
  • Merge Convert Branches: Merge all relevant convert branches into the ‘convert-to-artbox’ branch.
  • Squash Commit History: Squash the commit history of these merges into a single commit to simplify history.

Step 2: Construct Feature Branches from the Common Base

  • Update the Common Base: Ensure that the ‘convert-to-artbox’ branch is up to date with the latest changes.
  • Clone and Layer Commits:
    • Clone the ‘convert-to-artbox’ branch.
    • Pick and apply commits from each existing feature branch onto this clone.
  • Replace Old Feature Branches:
    • Delete the old feature branches.
    • Rename the cloned branches to replace the old feature branches.
  • Repeat for All Feature Branches: Perform the above steps for each feature branch that needs updating.

Step 3: Construct Artbox from the Common Base and Feature Branches

  • Reset Artbox Branch: Reset the ‘artbox’ branch to the ‘convert-to-artbox’ branch to incorporate the latest changes.
  • Merge Updated Feature Branches: Merge all updated feature branches into the ‘artbox’ branch to consolidate the changes.

Convert Branches

A convert branch is used to adjust the latest GIMP master branch to support the Artbox feature branches or to make specific changes to the default GIMP application. These branches are merged into a single ‘convert-to-artbox’ branch, which serves as the common base layer.

The current strategy is to place any heavily modified file that supports multiple feature branches—through the addition of new data structures—into a convert branch. This approach helps consolidate overlapping changes in one place, while maintaining the core code that performs the main functions in separate feature branches.

The current convert branches are:

  • convert-to-artbox: The main branch that combines all other convert branches.
    • convert-data-remote: Handles the gimp-data remote url.
    • convert-context-all-merged: Consolidates context-related changes.
    • convert-paintbrush-all-merged: Handles the GUI changes and additional options for the Paintbrush Tool
    • convert-pref-all-merged: Merges changes to preferences.
    • convert-force-artbox-config: Forces a specific config folder for Artbox.
    • convert-name: Manages web-links and renaming of GIMP strings to Artbox.
    • convert-readme: Updates the README.md
    • convert-git-lab-build: Asks GitLab to only build the Artbox branch.

Identifying Conflicts

Updating Artbox to the GIMP development branch involves identifying any conflicts or changes introduced by GIMP that overlap with Artbox changes.

  • First Stage Conflict: Rebasing the convert branches to GIMP master branch.
  • Second Stage Conflict: Cherry-picking the merges from feature branches onto the new common branch.

These conflicts can be resolved fairly easily due to the automated construction process and granularity of the changes.

Example of a Convert Branch

A unusually complex convert branch like ‘convert-paintbrush-all-merged’ is a branch that integrates multiple smaller changes, it’s commit history is more than one change.

  • convert-paintbrush-all-merged: Integrates modifications to the paintbrush tool, history is intact.

If a conflict arises between convert-paintbrush-all-merged and the GIMP development branch, an interactive rebase can be done to edit and resolve that particular commit.

Feature Branches

Feature branches are concerned with the core code implementation of a new feature. They may rely upon a convert branch to have paved the way with additional GUI options, preferences or other global variables. The ideal feature branch would be a one tiny change, like Dynamic Velocity Output. The worst case is a system wide feature, like Resource Control.

Notes

The key difference between a feature branch and a convert branch is that feature branches build on top of the convert-to-artbox branch. In contrast, a convert branch is an adjustment made directly to the GIMP development master branch.

InstallationTroubleshooting