1. Using Integrity Change Packages for Development
Joe Bartlett
July 22, 2014

2. Table of Contents Overview: Describe change packages at a high level
Overview of change package types
Change Package policies
Integrations
Scenarios:
Simple check-in and check-out
Propagations
Change Package Review
Change Packages as Auditing
Best Practices
Common Problems
Questions

3. Change Packages – What Are They?
Change Packages are objects in Integrity used to contain and track changes made to SI projects, subprojects, and members.
These changes can include things like creating new projects/members, as well as updates such as check-ins, propagations, etc.
Only the creator of a change package can add entries to that change package.
A change package number is always in the form X:Y where X is the container ID (an Integrity Item if the SI-IM integration is enabled under Global Policies) and where Y is the next available relative number.

4. Why Use Change Packages?
Change packages provide the following advantages:
Change packages allow related changes to be grouped as a logical unit.
Change packages allow work in progress to be submitted to the repository (server) all at once (using submit change package), which prevents users from partially submitting related work in progress. This can be controlled with the use of the Change Package Transactional policy.
Change packages provide a way to apply related changes to a project or Sandbox in one operation. This allows changes to be applied from one development path to another without the need for manual merging unless changes conflict.
Using change packages, users are able to resync the changes required to address a specific item without resyncing the entire project.
Groups of changes can be reviewed as a unit. If reviews are mandatory, changes are reviewed before they are committed to the server repository.

5. Change Package Types
Change packages may be one of several different types:
SI – This type is used when the Integrity Server is SI-only and has no IM functionality. These CPs cannot be used with IDE integrations such as Visual Studio and Eclipse.
Development – These are the most common kind of CPs. They are linked to an Integrity Item which can be seen from the Change Packages tab of the item.
Propagation – These CPs are used when propagating changes between development paths and contain other change packages.
Implementer – These CPs are used for the Integrity – Implementer integration.
Other – It is possible for customers to create their own custom, new type of change package. Not very common, and only do-able from the CLI.

6. Change Package Policies
Found in the Admin Client under Configuration Management -> Policies.
Policies can be set at the Global level or at the project/subproject level.
Change Packages Enabled: Controls whether CPs are able to be used.
Use Change Package Tracking Labels: Legacy functionality, not often used.
Change Packages Mandatory: Controls whether CPs are mandatory for SI operations.
Change Packages Transactional: If set to True, then all entries become pending until the CP is Submitted. If set to False, changes apply immediately even with the CP open.
Change Package Review Enabled: Controls whether CP Review is enabled.
Integrity Manager Enabled: If set to True, the IM – SI integration is enabled and allows CPs to be attached to Items.
Integrity Item Mandatory: If the IM – SI integration is enabled, this determines if an item must be attached to the CP when created.
Change Package Reviewers: If CP Review is enabled, this determines which users/groups are set as the principals to review submitted change packages.
Change Package Watchers: If CP Review is enabled, this determines which users/groups get notified when a CP gets closed.

7. Integrations
Configuration Management integrations (Visual Studio, Eclipse) generally make use of change packages to allow users to work within their preferred IDE and still gain the benefits of tracking their changes in Integrity.
Note that although change packages are mandatory for Visual Studio, Eclipse may be used without them.
SI-only change packages are not able to be used with the Visual Studio or Eclipse integrations.
Custom change packages may be used for a custom integration if desired, though usually the built-in Development change packages are suitable.

8. Other Ways to Access CPs
Change packages are also exposed in the trigger bean framework, CLI, API, and web services.
Custom reporting, interfaces, etc. can be built to leverage this information using any of the supported frameworks.

9. Common Change Package Scenarios

10. Scenario 1 – Simple Check-Out and Check-in
When checking-out a member, an open change package created by you can be selected from the drop-down or a new one can be created with the Create button.
The CP will contain an entry for a Lock on the member (Exclusive or Non-Exclusive will depend on your locking policies).
When edits are finished and a check-in is done, the entry will change from a Lock operation to
an Update operation.

11. Scenario 2 – Change Package Review
To control changes being committed when a change package is submitted.
When CP Review is enabled, a submitted change package does not get committed automatically. The CP entries become Pending until accepted or rejected by a CP Reviewer. Once accepted, changes get applied.
You can see any CPs waiting for you to review by going to Change Package
-> View My Reviews. notifications are also sent to reviewers.

12. Scenario 3 – Propagating Changes Between Development Paths
There are 3 scenarios for moving changes between development paths:
ResyncCP
This process allows you to select a group of change packages with the actions you want, and perform merging to resolve any conflicts inside a sandbox. Once all the merging is complete, the propagation change package can be submitted and applied.
ApplyCP
Similar to ResyncCP except ApplyCP is done in a project context rather than sandbox, and does not provide the option to merge conflicts.
Merge Child Development Path (2009 SP5+)
Developed as a more user-friendly way to merge changes from a development path up to its immediate parent only.

13. Using ResyncCP
In a Sandbox context, select the project where changes will be propagated to and select Change Package -> Resynchronize.
On the pop-up dialog, add the relevant change packages by entering the IDs or querying for them with the Find button. Click Add.
Create a propagation CP to contain all of the development CPs holding changes to the project/members.
Perform any manual merges to resolve conflicts.
When done, Submit the propagation CP to commit the changes. Handle any CP Review if necessary.

14. Using ApplyCP Almost exactly like ResyncCP.
In a Project context, select the project where changes will be propagated to and select Change Package -> Apply.
On the pop-up dialog, add the relevant change packages by entering the IDs or querying for them with the Find button. Click Add.
Create a propagation CP to contain all of the development CPs holding changes to the project/members.
The operation will tell you if merging is needed and cannot be completed (use ResyncCP instead).
When done, Submit the propagation CP to commit the changes. Handle any CP Review if necessary.

15. Using Merge Child Development Path
In this example, DevPath1 is based off the mainline and DevPath4 is based off DevPath1.
The Merge Child Development Path tool would only be able to propagate changes from DevPath1 to the mainline or from DevPath4 to DevPath1 for example.
Only 1 ‘jump’ is allowed and only going up to the parent path.
Changes could not be propagated from DevPath3 to DevPath4 or from DevPath1 to DevPath4.
Larger jumps need to be handled by ResyncCP or ApplyCP.

16. Using Merge Child Development Path (cont’d)
Highlight the desired PARENT project context for changes to be propagated into.
Go to Project -> Development Path -> Merge Child Development Path.
In the pop-up dialog select the CHILD development path to merge into the parent, and select the Integrity Item for the propagation CP to be created against.
Manually merge any conflicts and save the outcome (creates new working files in the sandbox).
If necessary, Submit the CP and go through any CP review.
Project history will show the merge arrow between checkpoints and new checkpoints with descriptions are made automatically.

17. Change Packages as Auditing
Change packages can be used to track many types of Source operations if they are enabled and used.
The Change Package -> Find gesture can query on nearly all aspects of a CP.

18. Change Package Best Practices

19. Best Practices Keep it simple.
Keep CP entry count relatively low (<1000). The changes in each CP should reflect a certain unit of work (ie. Change web page icons to be yellow).
Avoid having entries for different top level projects in the same CP (RFC ).
Avoid having change packages with entries for more than one development path of a project.
Do not have CPs with entries which both move subprojects and update members in the original location (RFC ).
See Article for best practices when propagating changes across dev paths.
The Integrity Client User Guide has a section about CPs called “Grouping Units of Work in Change Packages”. See this for detailed usage info.

20. Common Change Package Problems

21. Common CP Problems
Moved Integrity to new server, need to run fixcpservers. CPs are bound to a hostname and port so a client can connect to multiple servers and use CPs from all of them.
CP entries referencing dropped dev paths. When a variant is dropped, the name is no longer available in project history but references still exist in CP entries.
Confusion around archives displayed in CPs. Use the Location field to show actual archive name and location. Useful for shared or renamed members!

22. Common CP Problems (cont’d)
Unable to handle multiple Change Package entries for the same member with different backing archives. This happens when using ApplyCP/ResyncCP but the change package(s) involved have entries for the same member name, but different archive locations. This commonly occurs from adding a new member with the same name as one that was dropped in that project and the user selected “Create a new archive” when prompted:
See RFC which asks to prevent this situation from happening.

23. Stage and Deploy Stage and Deploy is not covered by this presentation.
For details regarding Stage and Deploy, please refer to the S&D Learning video created by Ray Rahman.

24. Future Initiatives
Change Packages knowledge hub is currently being worked on but not published yet. Contact Ann Walsh if you are interested in contributing.

25. Questions?
Are there any questions about change packages not answered by the presentation?