Dear Colleagues,
Per my AI
from the ODATA TC meeting on August 9, 2012 here is a brief
outline of a proposal for change tracking of specification
artifacts and a build process for managing the life cycle of a
spec artifact.
A similar
process has been in use by the RegRep TC for many years. The
basic idea is to use a process for managing spec artifacts that
is modeled after that which is used by most Open Source projects
for managing software source code artifacts.
I will update
this document based on comments received on the ODATA TC mailing
list or offlist.
Version
Control of Specification Artifacts
- Manage
all specification artifacts in a publicly accessible git
repository (e.g. github). If we cannot use git or another
distributed VCS (e.g. hg) for some reason then fallback is
to use OASIS provided svn
- Ideally,
only source artifacts are managed in source control.
Generated artifacts such as pdf, html etc. are ideally
generated in the build process
- Editors
MAY update documents in source control any time without
informing any one. TC members should be able to receive
commit messages to git if they wish by subscribing to a
commit mailing list
- Editors
MUST commit all spec artifacts to source control for
delivering each working draft and sub-working draft
- When
a release of the spec is cut, specific versions of spec
artifcats are automatically tagged within source control
with the release tag (e.g. odata-core-v1.0-wd01). This makes
it always possible to recreate a released version of spec
from source control using that tag.
Managing
Issues In JIRA
- Create
version in JIRA for only WD, CD, OS stages and not for
sub-versions of a WD
- Create
components in JIRA for any components of the specification
(e.g. odata-core, odata-json, ...)
- When
filing issues tag it with the JIRA defined version (e.g.
WD01) and component (odata-core). In the description
reference any sub-versions (e.g. WD01-03)
Building the
Specification Bundle
- A
single specification project has a single artifact to
deliver. Typically this would be a zip file
- Complex
spec projects may be organized in multiple sub-components
where each sub-component is a spec project and delivers its
own single artifact
- Building
the spec artifacts into a package and cutting a released
version of the spec are tightly controlled, highly
repeatable processes that are automated using maven as a
build / configuration management tool
- For
a general overview of benefits derived from use of maven
see:
http://sourceforge.net/apps/mediawiki/ebxmlrr/index.php?title=Whymaven
- Using
maven to manage project build and configuration is best done
by organizing spec artifacts to conform to established maven
conventions. All this means is that is follows a
well-defined and established directory structure and
provides a pom.xml file (similar to a ant or make file) that
defines the build process
- The
maven project may be multi-module if we feel that
sub-components of the spec need to be delivered as separate
artifacts (e.g. zip files)
- The
version of the spec can be managed by two properties in the
maven pom.xml file. Following is an example for for WD01
with sub-version 03 (could use date if we want but numbers
seems easier to compare visually IMHO):
<properties>
<spec.version>v1.0</spec.version>
<spec.stage>wd01-03</spec.stage>
</properties>
- The
maven-assembly-plugin is used with a custom assembly
description to build the spec project artifact as a zip
file. The structure of the zip file is designed to match
what is expected to be formally published to the
http://docs.oasis-open.org site
- The
spec project is built using normal maven build process: mvn
install
- The
result of build is the zip file for the current version of
the spec project: odata-core-v1.0-wd01-03.zip
- The
contents of the zip file are organized (by the assembly
description file src/main/assembly/assembly.xml) such that
one could simply extract it in the
http://docs.oasis-open.org site to get the latest version of
the spec published. This step also could be automated with
maven but requires OASIS to give editors secure access to
the target publish web site
Cutting a
Release of Specification
- When
it is time to cut a release, the maven-release-plugin is
used.
- It
automatically tags the version control system files with the
release tag (odata-core-v1.0-wd01),
- It
builds the project and produces the artifact
odata-core-v1.0-wd01.zip (notice no sub-version number 03
for final delivered artifact for WD01).
- It
updates source control files to automatically bump up the
version number in preparation for the next release (e.g.
v1.0-wd02)
- Cutting
a release is one place where having a distributed VCS (not
svn) is really important. Release can be cut in a clone of
the master repo. If mistakes happen the master repo can be
recloned and process repeated. If no mistakes occurs than
clone repo can be published to the master. With svn you do
not have this extra level of insulation from mistakes.
- Lastly,
it has been proposed sometime back by me to OASIS that if
they institutionalize this kind of a process then downstream
work on their side can also be automated when publishing
spec artifacts
--
Regards,
Farrukh Najmi
Web: http://www.wellfleetsoftware.com
|