-
Notifications
You must be signed in to change notification settings - Fork 17
Versioning artifacts
This page describes, how to version artifacts, e.g. software tools, frameworks or documents
Versions consist of three numbers, e.g. "1.3.1". All digits start with a "0" for the first release, so the first version is always "0.1.0". The digits of a version number have the following meaning: major.minor.service. An increased number in one of the digits marks the corresponding type of release of an artifact, e.g a version increased from "1.0.1" to "1.0.2" marks a service release, while a version increased from "1.0.1" to "1.1.1" marks a minor release. The three types of releases have the following meaning:
- Service: Only contains fixes, does not add any new API (for software) or content (for documents).
- Minor: Adds new API (for software) or content (for documents), but remains compatible to the last minor release.
- Major: Changes existing API (for software) or content (for documents) and is not compatible with the previous major release
After the three numbers, a qualifier can be added to specify the state of an artifact:
- 0.1.0.draft: The ongoing development, which leads to the release 0.1.0
- 1.2.1.M1: The first milestone on the road to release 1.2.1
- 1.0.0.RC1: The first release candidate for release 1.0.0
Versions should only be increased once in preparation of a release according to the versioning scheme. Versions should not be increased during on-going work. Git will do the versioning during this period.
Only graduated projects are allowed to do releases starting with a "1" or higher.
There should be always a file in the repository for the last version of on-going work. Version numbers should not be reflected in file names, only within the file of an artifact.
Once a release is done, the latest state of this file can be copied to another location (folder) to make it available for download. These copies are not changed anymore and can include the version number in the file name.
The last commit of a document before the release should be tagged, e.g. "Release 1.1 of document xy" A released document should contain the name of the tag. This allows to re-created the latest state of the document based on a certain release, e.g. for branching from it.
This section describes an example for the versioning process based on a document
A new document is created
Repository Structure:
/myDocument/myDocument.tex
/myDocument/fileBelongingtoDocument.tex
Document Content:
Version: 0.1.0.draft
First Chapter
Committers work continuously on the document and add content. The version number is not increased. After this period, the document might look like this:
Repository Structure:
/myDocument/myDocument.tex
/myDocument/fileBelongingtoDocument.tex
Document Content:
Version: 0.1.0.draft
First Chapter
some text
Second Chapter
some more text
Committers want to get a review. Therefore they publish a release candidate RC1. The update the version in the document and create a tag in git for this commit. For conveniance, the create a downloadable artifact for reviewers:
Repository Structure:
/myDocument/myDocument.tex
/myDocument/fileBelongingtoDocument.tex
/myDocument/releases/myDocument-0.1.0.RC1.pdf
Document Content:
Version: 0.1.0.RC1
Git Tag: myDocument-0.1.0.RC1
First Chapter
some text
Second Chapter
some more text
After recieveing feedback from the reviewers, another release candidate can be published, until the reviewers are satisfied.
Once a release candidate is accepted, a release can be done to publish the results. Again the version number is updated in the document, a git tag is created and the results are published for direct download.
/myDocument/myDocument.tex
/myDocument/fileBelongingtoDocument.tex
/myDocument/releases/myDocument-0.1.0.RC1.pdf
/myDocument/releases/myDocument-0.1.0.RC2.pdf
/myDocument/releases/myDocument-0.1.0.pdf
Document Content:
Version: 0.1.0
Git Tag: myDocument-0.1.0
First Chapter with some changes from review
some text
Second Chapter
some more text
Once a release is done, the next release is planed and the version number of the document is already increased. This does not affect published releases. Depending on the goal of the release, the version number is increased at least in the "service digit". If there are more fundamental changes during the work period, the version number needs to be adapted again.
If there are many releases and release candidates, the published results should be ordered:
/myDocument/myDocument.tex
/myDocument/fileBelongingtoDocument.tex
/myDocument/releases/0.1.0/myDocument-0.1.0.RC1.pdf
/myDocument/releases/0.1.0/myDocument-0.1.0.RC2.pdf
/myDocument/releases/0.1.0/myDocument-0.1.0.pdf
/myDocument/releases/latest/myDocument-0.2.0.RC1.pdf
/myDocument/releases/latest/myDocument-0.2.0.pdf