Difference between revisions of "OOPM:Development:Documentation:HowTos:WikiVersioning"

Revision as of 20:41, 8 May 2009

HowTo: Versioning Wiki Resources

Introduction

TBD information on why to use versioning and why not to simply fall back to revisioning, information on how wiki resources will be versioned using a simple version identifier consisting of a release number and a version number, with the wiki taking over the responsibility for handling revisioning. CONSIDER whether wiki resources require a version state, e.g. draft during the inception phase, or whether that state information is purely informational and not part of the actual release version number.

The following wiki resources must be versioned in order for us to backtrack our work not only by the MediaWiki provided revisioning facility, but also by being able to navigate directly to past versions of all of our resources, for example articles, aka single/multi page documents or article fragments, imagery/illustrations, or templates etc.

• Articles
• Article Fragments
• Media
• Templates

What will not be versioned are the following (special) resources offered by MediaWiki:

• Categories
• User Pages
• Discussion Pages
• Discussion Archive Pages
• FAQs, HowTos
• Media included with the above User Pages, Discussion (Archive) Pages, FAQs, or, HowTos

Versioning Wiki Resources

Release Version Identifier

The release version identifier being used with the individual wiki resources for which we will apply our versioning scheme, is defined as follows

ReleaseVersionIdentifier ::= ReleaseNumber '.' VersionNumber ReleaseState

Where

ReleaseNumber ::= [1..9]+
VersionNumber ::= [0..9]|([1..9]+[0..9]*)
ReleaseState ::= draft|ε

Please note that there is no whitespace between the VersionNumber and the ReleaseState.

The identifier is an inherent part of the wiki page name.

Examples

• [[FooBar:1.0draft]], where version 1.0draft of the FooBar document resides in the global namespace
• [[FooBar:1.1draft]], same as above but version 1.1draft
• [[OOPM:Development:Documentation:Requirements Analysis:1.0]], where version 1.0 of the RA document resides in the namespace OOPM:Development:Documentation:Requirements Analysis

Instantiating a New Versioned Wiki Resource

In order to create a new versioned document, you will have to either edit an existing page, insert the wiki page link and use the preview function, so that you then may go and create the referenced wiki page.

You may also use your personal page or the discussion page thereof for starting up new pages in the wiki.

TBD add documentation on versioning of other resources, for example media and other attachments

Instantiating a New Version From an Existing Versioned Wiki Resource

In order to instantiate a new version from an existing wiki resource, for example a page, you will first have to edit the originating version. Simply copy all of the relevant information to the clipboard and then use the aforementioned procedure to create a new versioned wiki resource, in this case the new wiki page. Then you will paste all of the available data in the clipboard, that you previously copied from the originating version and edit it as required.

Note that for multi page documents that incorporate changes to either subpage thereof, you will have to recursively copy and recreate all of the affected resources.

TBD the below is actually based on the toc template to be introduced for documentation purposes

TBD we will also provide the MasterTOC template provided in this wiki for inter-linking the indiviual pages/sections in our documents. see Template:Documentation/MasterTOC for more information. Therefore, the information provided in the TBD TOC for our own documents must be in a format so that we may include it in the provided MasterTOC as the value for the parameter toccontent, e.g. {{myowndocumentTOC}}, regardless of whatever additional templates will be used for authoring the actual TOC.

Examples

• Multi Page Document [[SampleMultiPageDocument:1.0]]

; Title
:; [[SampleMultiPageDocument:Chapter1:1.0]]
:; [[SampleMultiPageDocument:Chapter2:1.0]]
:; [[SampleMultiPageDocument:Chapter3:1.0]]

The above document will incorporate changes to chapter 2, whilst chapters 1 and 3 remain in their respective original versions.

First, we will have to copy the above wiki markup of the original version 1.0 of the SampleMultiPageDocument to the new wiki page [[SampleMultiPageDocument:1.1]]

Next, we will edit that document and point the chapter 2 reference to the next version of chapter 2

; Title
:; [[SampleMultiPageDocument:Chapter1:1.0]]
:; [[SampleMultiPageDocument:Chapter2:2.0]]
:; [[SampleMultiPageDocument:Chapter3:1.0]]

and save the changes to version 1.1 of our document.

Third, we will now copy the wiki markup from the original chapter 2, version 1.0 to the new wiki page for chapter 2, version 1.1, using the above link and insert the markup there. Now we can change the chapter to our likings and save the page.

We now have two working versions of the same document in our wiki, that we can use for tracking our history of changes incl. also the history of changes to the structure and information in those document. That way we can easily manage multiple releases of our software incl. also its documentation.

TBD add documentation on versioning of other resources, for example media and other attachments