Dita Release Management
- 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