The document discusses software release management applied to DITA. It analyzes common problems people face with managing multiple releases, versions, and variants in parallel. Key use cases are branching to allow parallel work on multiple versions, but other solutions may be better for variants and release cycles. The presentation demonstrates how to use a version control system for branching, an artifact repository for dependencies, and continuous integration for builds and testing. It provides an example scenario of sharing content between user and training documentation with different release schedules. The conclusion recommends branching for parallel work, splitting content into projects for different products/teams, and using artifacts, repositories and continuous integration.

1. STRUCTURED
CONTENT
MANAGEMENT,
UPDATED
DITA Release Management
Frank Shipley

2. Presentation overview
• The problem analyzed
• The principle use cases
• Software release management applied to DITA
• Demo
• Conclusion
2

3. The problem analyzed
An analysis of what people in the
DITA community are saying about
release management.
3

4. The problem analyzed
Quotes taken from whitepapers, articles, presentations and discussions Main theme
“Multiple releases at one time”, “Multiple parallel releases”
“Ability for teams to work in parallel on a range of versions”
“Update previous versions of documents more often which results in having to
manage multiple versions of the documentation in parallel”
“Versioning for future versions along with current versions”
“Edit files for an upcoming release while retaining the capability to publish or
translate earlier release of the same files”
Multiple versions
in parallel
“Multiple variations”
“Maintain different documentation for different versions of the product or
variants of the product documentation for different customers”
“New customized products”
“Teams frequently share content where different users may need to make
variations on content for a specific deliverable”
Multiple variants
“Bringing together multiple components that are all developed on their own
schedules”
“Multiple versions of products overlapping through the manufacturing or
development process”
“Shorter schedules”, “Rapid product release cycles”
Multiple release cycles
4
Sources:
CIDM release management whitepapers, webinar, articles and presentations (http://www.infomanagementcenter.com/index.php?page=3592)
DITA users group (http://groups.yahoo.com/neo/groups/dita-users/conversations/topics/21270)
dita.xml.org (http://dita.xml.org/blog/is-uncertainty-making-release-management-difficult)

5. The principal use cases
• Multiple versions in parallel
• Multiple variants
• Multiple release cycles
5

6. Multiple
versions
in parallel
• Branching allows work in parallel on multiple versions
• Branching is the best solution
• Release branches may be kept for future releases
v1.0 v2.0
v1.1
Release branch
Time

7. Multiple
variants
• Branching allows work in parallel on multiple variants
• Branching may not be the best solution
• If the changes cannot be merged, the product branch will have to be kept
• What other solutions are there?
v1.0 v2.0
Product 1
Product 2
Product 1Shared
content
Time
Product 2
Product 1
Product 2
Product branch

8. Multiple variants
• Alternate solutions to branching
– Conditional processing
– Duplicating the topics
– Use conref or conkeyref
Strategy pattern
“Identify the aspects of your documentation that
vary and separate them from what stays the same”
8

9. Multiple
release cycles
• Branching allows work in parallel on multiple releases
• Branching is one possible solution
• What other solutions are there?
Product 1
Product 2
Product 1
v1.0
v2.0
Time
Product 2
Shared
content
Product 1
Product 2
v2.0

10. Multiple release cycles
• Alternate solutions to branching
– Link to specific versions of topics
• How best to do that?
10

11. Use cases: Summary of requirements
11
Use case Summary of requirements Need to branch
Multiple versions
in parallel
Work in parallel on multiple versions
(releases) in order to work on future
releases and still maintain existing
ones.
Mandatory
Branching is the best solution
Multiple variants Work in parallel on multiple product
variants so that the work in progress
on one product variant does not
interfere with the work in progress
on another product variant.
Optional
Branching may not be the best solution
Multiple release
cycles
Perform releases for some products
while work is in progress on other
products.
Optional
Branching is one possible solution

12. How many branches: example scenario
• 2 products
– 1st product released in Q1
– 2nd product released in Q2
• 3 versions
– current development version (n+1),
– latest production version (n),
– previous production version (n-1)
How many branches?
• Best: 3
• Worst: 12
– If products have specific variants that can’t be merged
– If products share content that doesn’t apply to both releases
12

13. Multiple
projects
• Shared content is put into a separate shared project
• Main project has a dependency on the shared project
• No branching and no merging
Product 1
Product 2
Product 1
v1.0
v2.0
Time
Shared
content
Product 2
v2.0 v3.0
v2.0
Dependency Dependency

14. Is branch and merge the answer?
Yes - for managing multiple versions
Probably not - for managing multiple product variants
and release cycles!
14

15. Multi-branch or multi-project
• When to branch:
– When managing multiple versions
– When working in parallel
• When to split into multiple projects
(or project modules)
– When content is shared between products that have
different release cycles
– When there are dependencies on external artifacts
– When content is developed by different teams
15

16. Software release management
applied to DITA
16

17. Software release management
Wikipedia
“Software configuration management is the task of
tracking and controlling changes in the software…”
“Software release management is the process of
managing software releases from development
stage to software release…”
17

18. Software release management
3 pieces to the puzzle:
• Version control system (VCS)
– To store and manage the source files
• Artifact repository
– To store and manage published artifacts
• Continuous integration server
– To build the software (artifacts)
– To run automated regression tests
18

19. Version control system (VCS)
“…a tool for managing a collection of program code that provides you
with three important capabilities: reversibility, concurrency, and
annotation.”
Eric Raymond. Understanding Version-Control Systems
• Reversibility
– Can’t loose anything
– Can go back to a previous point in time (snapshot or tag)
• Concurrency
– Allows parallel development through branching and working copies
• Annotation
– Know what changes have been made by who and when (traceability)
Your VCS or CMS provides these capabilities for your DITA source files.
19

20. Example branching strategy
• Development branch: Trunk
– Latest development (unstable) version of the code
– Infinite lifetime
• Release branches
– To manage multiple versions in parallel
– Can branch from trunk or from any previous release to create a new release branch
– The release branch is kept as long as the corresponding version is being maintained
20
1.0 1.1
2.0
Release 1
Release 2
Trunk

21. Example branching strategy
• Feature branches
– To work on new features (new products or product variants) in parallel
– Isolates your work from other features and from the trunk branch
– Should be short term branches that are merged with the trunk branch
as soon as the feature is completed
– Could also be related to a hot fix (hot fix branch)
21
1.0 1.1
2.0
Release 1
Release 2
Trunk
Feature

22. Artifacts and repositories
• Artifacts:
– A set of resources produced by a software build process.
– In the Java world this is usually the compiled Java class files and
associated resources packaged in a JAR file.
– In the DITA world this could be a zip of your source files and/or the
published output.
• Artifact repository:
– A central place for storing published artifacts so that they can be
shared over the network via SSH, HTTP or FTP.
– Popular artifact repository managers:
• Apache Archiva
• JFrog Artifactory
• Sonatype Nexus
• DITA artifacts could be stored in an artifact repository.

23. Dependency management
• Dependencies and transient dependencies
– Artifacts (software programs or libraries) often require other artifacts
in order to function correctly.
– Those artifacts in turn may require other artifacts themselves.
– We call these artifacts dependencies and transient dependencies.
• Dependency management
– The mechanism whereby all of the dependencies and transient
dependencies for a software program are resolved.
– Popular dependency management tools:
• Apache Ivy
• Apache Maven
• Gradle
• DITA dependencies could be managed in the same way.

24. Sharing content between teams
and across boundaries
24
Artifact
Repository
Artifact
Repository
Artifact
Repository
Artifact
Repository
Build / Continuous
Integration
Build / Continuous
Integration

25. Release and snapshot artifacts
• Release artifacts
– Final documents
– Only one release for each version
– Can only have dependencies on other release artifacts
• Snapshot artifacts
– Work in progress documents
– Can be created at any time before a version has been released
– Allows you to share your work in progress with others
– Can have dependencies on both release and snapshot artifacts
1.0
Snapshot 130901
1.0
Snapshot 130915
1.0 Release 2.0
Snapshot 131015

26. Continuous Integration
• Automate the build process so that all
software changes are integrated and tested
on a continuous basis
• Primary goal is to detect integration problems
and perform automated regression testing
• Popular continuous integration tools
– Atlassian Bamboo
– Jenkins
– Travis

27. Demo
• Componize: Source repository, build pipelines (VCS)
• Maven: Artifact repository, dependency management
• Jenkins: Continuous Integration
• Scenario
– User and training content
– The training content
• is released one month later than the user content
• reuses content from the user content
– We need to work in parallel on the user content for the
next v2.0 release while the training content is being
finished for the current v1.0 release

28. Conclusion
• Release management is not just about branch and merge
• Use branching:
– When managing multiple versions
– When working in parallel
• Split source files into multiple projects (or project modules)
– When content is shared between products that have different release
cycles
– When there are dependencies on external artifacts
– When content is developed by different teams
• Store published artifacts in an artifact repository
– So they can be easily shared with others
– So they can be easily integrated into a continuous build environment
• Use continuous integration
– To detect integration problems
– To perform regression testing
28

29. STRUCTURED
CONTENT
MANAGEMENT,
UPDATED
Thank you – Questions
frank.shipley@componize.com
www.componize.com