This document describes the process of Integration of tasks between branches in the TyBugs project management software. This is considered an advanced topic, and readers are expected to already have a clear overview of how TyBugs operates.
Multiple Products derived from a Single Codebase
It is typical for an organisation to have several projects or products which share a single codebase. Not all products will use all aspects of the codebase, however there are some amounts of overlap between each product. This may be several editions of a single product, each with minor variations, or this may be several substantially different tools which happen to share a common programming framework.
In each of these cases, a defect or change in one product may easily impact on other products. It usually does not make sense to test each product in isolation, since this divides the testing resources unnecessarily and increases the likeliness that a defect or change would go unnoticed. At the same time, you generally won’t want to force testers to immediately follow up each bug report by testing in every single product. Finally, fixes or feature additions may make it into one product initially, but future releases of other products may then contain the same features and fixes.
When the team is already using a source control package (such as Perforce, Mecurial, or Subversion) this structure is probably already in place- so you’ll ideally configure your TyBugs project to match your source control layout. If you’re setting up a new project, then one common approach is to use a single “trunk” which represents the most recent development state of your codebase, and then introduce a variety of per-product, per-feature, or per-developer “branches” which are snapshots of part or all of the trunk. Integration is performed between the trunk and the branches, or (in more complex structures) between branches and their sub-branches.
Multiple Versions of a Single Product
A given product will usually have some form of version or build number which allows the user of the product to identify which features and fixes are present in the product, whether a newer version of the product is available, and which ideally allows the development team to associate the final product with a particular production date and/or historical state in the team’s source control package. These versions may take the form of a memorable name, a date, a sequential number, or so on.
TyBugs requires the project team to manually distinguish between separate versions of a product. A “branch” in TyBugs describes both the product in question, and also the specific version of that product (eg. “Mac OS X Snow Lion Server 10.7.3 (11D50d)” would be a single branch.) Branches may also be used to describe the current work-in-progress state of a particular product or source control branch (eg. “Trunk- Head Revision” or “Color Printer Support- Next Beta”)
It is possible for a branch to contain some features which are not visible in the final product. These features may be temporarily disabled, or not relevant to a particular edition of the product. As a result, it is feasible that a task or bug is present in a branch, but that the task or bug is not meaningful to users of the branch. This is not strictly a problem, but TyBugs users should be aware of this and filter out unnecessary information before passing on change-lists or other reports to stakeholders who may not be aware of this effect.
Creating a New Build of a Product
When a new build of a particular product is produced, the build engineer (or build script, or other responsible entity) should create a new branch representing the build output. Typically, this means renaming the existing “Head Revision” branch to reflect the product name and build number, and then creating a new “Head Revision” branch for any future development work. The new “Head Revision” branch should be configured with the appropriate permissions, added to any appropriate user groups, and have the newly renamed build branch set as its previous version.
The “previous version” history of a branch allows the TyBugs software and interested users to determine whether a particular bug or task is immediately relevant to an earlier or later version of the same product. It is not necessary or desirable to flag every open bug against every version of the product. Instead, tasks should be flagged appropriately in a given branch when tested, and only reflagged in later versions of the product if retested for some reason. This makes it clear what has been tested, and what is simply an assumption.
Multiple Components forming a Single Product
One particularly troublesome scenario is when a single product is formed of several discreet packages which are individually maintained. In the ideal case, these can be tracked as separate branches which requires no additional work, however in more complex cases it may not be immediately clear which component is the root cause of a problem, or the individual components or their versions may not be visible. This can make it difficult or impossible to maintain separate branches for the composite product.
In the event that the team elects to track a composite product as several individual branches, it is likely that some members of the team (or even all members of the team) will need to be prepared to move a task from one component branch to another. This may occur when a bug is reported against a particular versioned product (either the composite product, or a particular component product) but the underlying cause of the bug is determined to be in a different component product. This is one of the few cases where a TyBugs user is likely to want to remove a branch assignment from a task.
Integration between branches
When a project is using a source control package with multiple branches, “integration” is the process of moving changes from one branch into another related branch. Sometimes this occurs in a single direction (a provider issuing an update to some component that the project team is using) and sometimes this occurs in both directions (a product branch may be updated with the latest changes from another related product branch, perhaps via the “Trunk”.)
Integration in TyBugs allows the team to reflect the impact of these code movements onto the bug and feature tracking. New features which have been implemented in the source branch should be reflect onto the target branch. Fixed bugs should be marked fixed in the target branch. Newly found bugs should be marked as present in the target branch, and so on.
An integration between two branches is initiated by right-clicking the source branch in a branch list window, selecting “Integrate Branch…” and specifying the target branch for the integration. This process should be treated with some caution as the effects can be far-reaching and it is not possible to undo the changes in a single operation.
Once an integration is started, the TyBugs user is presented with a list of tasks which differ (in terms of status) between the two branches. Each task shows the current status in each branch so that the user is aware of what changes will result from the integration. The user may then select some subset of tasks and integrate them. This process may be repeated until all tasks are integrated or until the user is otherwise happy with the result.
It is important to note that TyBugs maintains an internal record of the order of branch state changes on a given task. This means that the integration window will not offer to overwrite a newer task status in the target branch with an older task status from the source branch.
The following diagrams show a step-by-step view of what happens to a single task across several branches which are undergoing regular integrations.
1. Three Branches
Our example team has one product release on two substantially different platforms- the iPhone, and Android. Since they have different developers and different release schedules for the two platforms, they use two separate branches to ensure that changes intended for one platform don’t cause problems with the release schedule for the other platform. They’re also intending to support other platforms in the future, so they maintain a separate ‘trunk’ branch for handling integrations between the various platform branches.
2. A Defect is Uncovered
During regular testing of the iPhone product, the Quality Assurance team identifies a minor issue, “Defect X”. This is entered into TyBugs as a task and is marked as “Open” in the branch “iPhone- build 398”.
3. First integration from iPhone to Android
A little while later, the project manager determines that it’s time to move the latest iPhone features across to the Android branch. An integration of the iPhone branch is made to the Trunk. The integration occurs in source control, and is mirrored in TyBugs. The defect which was previously known to be present in the iPhone branch is now known to be present in the Trunk.
For clarity: the bug may or may not have been present in Trunk previously, but since no tester reported it, it wasn’t clear up until this point. Now that we’ve integrated from a branch known to have the defect, it’s very much likely that Trunk also has it. If ‘Defect X’ was a truly serious problem, the project manager may have decided to delay integration until the Android branch was tested for the defect.
The Trunk is then integrated into the Android branch. Again, this is mirrored in TyBugs.
4. The Defect is Fixed.
Further development occurs on both platforms. The iPhone team is tasked with fixing ‘Defect X’ as a low priority task and they eventually sort it out.
5. The Fix is Integrated to the Trunk
Since we don’t have any release due in the near future and both platform developers are working on complementary features, the project manager instructs regular integrations back and forth. The fix for ‘Defect X’ makes it into the Trunk.
6. The Fix is Verified
The regular Quality Assurance processes test and verify that ‘Defect X’ has actually been fixed. The project manager is happy. As of this time, the Android team haven’t yet had an opportunity to grab the fix because they’ve been busy on other work.
7. The Verified Fix is Integrated
The next TyBugs integration to the Trunk carries along the new verification status.
And once the Android team finish up their work and take the next integration from the Trunk, they also get the verified fix.
At this point, ‘Defect X’ is fixed in all branches and, while a historical record of the defect still exists in the system, the team is not likely to refer to it again unless a similar problem occurs in the future.