Work packages

A work package is a group of tickets that is developed on one branch and reviewed in one pull request. The tickets usually sit under a parent ticket, for example a Jira Epic. Example: the Epic WR-40 "Hourly forecast" with three stories becomes the branch feature/WR-40-hourly-forecast and one pull request whose title and description name all three tickets.

Tracemoor keeps a list of the open packages, shows how far each branch is behind its base and which packages touch the same files, and runs the steps of the workflow: create the branch, keep it current, open the pull request, clean up after the merge.

Work packages are optional. Without them the Git view, the Tickets view and pull requests work as usual.

The Workflow Policy

The Workflow Policy describes how tickets become branches and pull requests in this project: base branch, branch names, pull request templates, ticket status per step and how a branch is kept current. It is stored in .codeexplorer/workflow.toml in the exploration and is shared with it.

The policy is off by default. The work package functions work either way, the policy only provides their defaults. When it is on, the AI follows it whenever it starts, syncs or finishes work on tickets. See Set up the Workflow Policy.

Life of a package

stateDiagram-v2
    [*] --> active: Start
    active --> in_review: pull request opened
    in_review --> in_review: Sync
    in_review --> merged: Finish after the merge
    active --> abandoned: Abandon
    in_review --> abandoned: Abandon
    merged --> [*]
    abandoned --> [*]

Base branch

Each package starts from the fresh remote state of its base branch, never from the branch that happens to be checked out. Its pull request targets the same branch. The policy sets the default base, for example develop. You can pick another base per package, for example release/2.4 for a fix that goes into a release.

One working directory

All packages share the one working directory of the repository. Switching to another package checks out its branch. Uncommitted changes of the current branch are put into a stash marked with that branch (ce-wp:<branch>). When you come back to the branch, the stash is applied again. Half-done work stays with the package it belongs to.

The changelist of a parked hunk is not kept. When the stash is applied again, its hunks land in the active changelist. Move them back if you had split them across changelists.

Stacked packages

A package can build on another open package when it needs code that is still in review. Example: package B starts from the branch of package A, and the pull request of B targets the branch of A. When A is merged and finished, B is moved onto the base branch and its pull request is retargeted. With the merge strategy B is restacked and has to be synced afterwards. With the rebase strategy B is rebased and force-pushed with lease.

Collisions

While a package waits for review, other packages land on the base branch. The status of each package therefore shows:

• how many commits it is behind its base,
• which files conflict with the current base (a trial merge in memory, the working directory is not touched),
• which open packages change the same files. Whoever merges second has to reconcile them.

Sync a package that is behind, and split or stack packages that overlap before the reviewer finds the conflict.

Where you work with packages

Limits

• Ticket providers: Jira Cloud and GitHub Issues. Bitbucket Issues cannot be used for packages.
• Pull requests: GitHub and Bitbucket Cloud.
• One working directory. Packages do not get separate worktrees.
• The list of packages is stored on this machine only (.codeexplorer/work_packages.json, excluded from Git). The branches and pull requests are shared through the remote as usual.