Publishing from SVN

Introduction

This page is a description and discussion of the process for V3 Publishing where the source artefacts are stored within Subversion.

Objectives

• Don (HL7 Publishing Coordinator) should be able to run publishing without direct intervention from WG or publishing facilitator
• WG needs to 'publish' (commit/checkin/make available) without intervention from Pub Coord
• Normative Edition is created once a year, compiled from previous NE materials and new successful ballots with minor rework (rework is one time affair)
• WG wishes to continue work on artifacts while in ballot cycle.
• WG wishes to be selective about contents of published ballot (current repository may contain more than the current ballot contents).

Background

There are various options for implementing a mechanism to provide better levels of automation while reducing overhead of all parties. The mechanism preferred was to establish a 'manifest file'. The manifest must provide 2 intersecting pieces of information, the files that comprise the ballot contents and the revision that defines those files. The following matrix illustrates:

Revision Matrix

File	Revision
	121	122	123	124	125
Artefact 1	•
Artefact 2			•	•
Artefact 3	•			•
Artefact 4	•
Artefact 5		•
Manifest File					•

It is important to note that in the Subversion paradigm, creating a revision ties the complete set of files together. In the above example, changing Artefact 5 and committing the change creates revision 122. Revision 122 in the repository consists of the changes to Artefact 5 as well as the changes to Artefact 1, Artefact 3, and Artefact 4 created in revision 121 and the state of Artefact 2 when revision 122 is created. GWB: to be clear, the manifest itself is not what is shown in the above table. I believe the table shows reality, but the manifest would be made up of the list of files and the assertion of a single revision to be used for publication. Thus in the above example, the committee might have released a manifest for publication at release 123 including all five artifacts, while the committee continued to work and produce release 124 without it yet been published.

The manifest for candidate ballot could be [Artefact 1, Artefact 3, Artefact 5] the base for the ballot would be rev:121. As he ballot proceeds, Artefact 5 is updated (rev:122) requiring ballot regeneration. Artefact 2 is updated (rev: 123) with no resulting change. And finally, Artefact 2 and Artefact 3 are updated (rev 124) which sees the updated Artefact 3 in a regenerated ballot.

Scenarios

Scenario 1: WG submits document set for ballot

1. WG creates base manifest (process from Woody) agreed
2. WG edits manifest to reflect content ballot (or regenerates it)(on omissions, Need a status on artifactStatus table that says ignore this artefact for now)
3. WG ensures that all updated files are committed to the main trunk.
4. WG submits manifest for (what to) inclusion in ballot (check in? Checks in, informs pub-coord?) (I recommend that the manifest (name set for each ballot cycle) be checked in as part of the commitment. Ideally, the release number of the manifest would coincide with the release number to be published, although that may not be feasible. Certainly, the check-in process needs to notify the pub coordinator. One possibility would be to use G. Forge document release capability, which allows for people to subscribe to particular documents. In this case, the manifest would be the "released" document, and the Publishing coordinator (and any other interested parties) could subscribe.

Scenario 2: Ballot is Published (or a preview)

1. Publishing Coordinator retrieves latest from repository (correction: the Publishing coordinator needs to retrieve the content based on the designated release number from the manifest, not the latest.)
2. Publishing process runs using artefact specified in manifest.

Scenario 3: WG updates documents submitted for ballot

1. WG synchronizes with repository (to ensure any updates are retrieved)
2. WG performs edits on artefacts.
3. WG commits updated artefacts to repository
4. WG (informs publishing coord? Continuous integration engine?) (Here, I believe the publishing facilitator from the committee must submit a new manifest that asserts a latter revision number, corresponding with the commitment in step three.)

Scenario 4: Publishing Support updates files to produce ballot contents

1. Publishing Coordinator synchronizes with repository
2. Publishing Coordinator edits necessary artefacts
3. Publishing Coordinator commits updated artefact to repository (here, we need a return notification to the committee. Ideally it should include a "list" (manifest?) For those items that publishing has changed. The challenge will arise in the circumstance where the original manifest included artifacts 12 and 3 (see table above) at release 123, the committee has proceeded to make local alterations at release 124, and publishing changes artifact 1 at release 125. At this point, there is a "garbled" manifest, as the correct release for artifact 1 is 125, where is the correct release for artifacts 2 and 3 are 123.

Scenario 8: Continued Work on an Artefact (not for ballot) during the ballot cycle

This scenario would require the creation of branch. The ongoing work would be done in the branch and then, following the ballot closing, disposition of ballot comments, and final updates of the balloted material, the branch would be merged back into the main trunk.

Glossary

Common version control system terms used.

Branch – also known as fork. Create a set of files that will diverge from the main trunk.

Check out – retrieve a set of files from the version control repository, does not imply 'locking' the files. Can be performed against a the main trunk, a branch or a tag

Commit – save a set of file changes in the version control system.

Lock – mark a file such that only the lock owner can update the file.

Sandbox -

Tag – associate a label with a consistent set of files. Often used to identify the files used to create a release.

Trunk – also known as Main Trunk. The main line of descent against which changes are applied.