STRUCTURED CONTENT MANAGEMENT, UPDATED DITA Release Management
Frank Shipley
Presentation overview The problem analyzed The principle use
cases Software release management applied to DITA Demo Conclusion
2
The problem analyzed An analysis of what people in the DITA
community are saying about release management. 3
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)
The principal use cases Multiple versions in parallel Multiple
variants Multiple release cycles 5
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
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
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
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
Multiple release cycles Alternate solutions to branching Link
to specific versions of topics How best to do that? 10
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
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 cant be merged If products
share content that doesnt apply to both releases 12
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
Is branch and merge the answer? Yes - for managing multiple
versions Probably not - for managing multiple product variants and
release cycles! 14
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
Software release management applied to DITA 16
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
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
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 Cant
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
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
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
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.
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.
Sharing content between teams and across boundaries 24 Artifact
Repository Artifact Repository Artifact Repository Artifact
Repository Build / Continuous Integration Build / Continuous
Integration
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
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
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
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
STRUCTURED CONTENT MANAGEMENT, UPDATED Thank you Questions
[email protected] www.componize.com