Table of contents
Undertanding the XRN schema
We now enter the structure of a XRN XML release notes file.
Is it worth reading all that?
Before considering reading this section, you have two possible caricatural attitudes:
- you have already taken a look at the release notes XML file, and you are a XSD wizard, so you think that you have already
have roughly understood what it is about. In that case, this section is just a reference for you, that you will refer in the
future when you are not sure about a feature;
- you do not know much about XSD, you still do not know how to fulfil your own release notes, you have some time do dedicate,
and you really want to understand what this is about. In that case, read on, we hope that the explanations here will be clear
There are chances that you are between the two attitudes. If you are bold, skip this section and remember that it exists,
when you meet some concepts that you do not understand. Yes, the most important is to remember that this section exists.
|It is important now that:
- either have a reasonable understanding of the XSD grammar and can understand the structure of a XML file via its XSD,
- or that you have a smart XML editor (like XMLSpy, Eclipse) that assists you when you modify your XML release notes file, i.e.
that ensures that what you type does not break the well-formness, and that even shows you the XML element and attribute that you can use, depending on your location within the file.
|This chapter is rather large, so you need to be courageous in order to read it all, otherwise, the rest of this guide might
seem you very obscure!
OK, so far, what we did was rather basic and straightforward. Straightforward, that is something that we obviously want to
keep. However, basic is not enough. So let's focus a little more about the anatomy of an XRN release notes XML file, so that
we can understand what kind of valuation piece of information can be expressed so as to make our release notes framework more
Definition of a release notes
|All that is explained concerning the structure of the XRN file may be submitted to change as the framework evolves. In order
to check the actual structure and some up-to-date explanation, it's often a good thing to take a look at the XSD (that we
have already introduced). It should be full of annotations, which can be looked at via the source, but even better via a smart
XSD editor like XMLSpy.
|You will find in may places the
ContentType XSD complex type definition. Just consider that this type enables to provide textual information.
|Some elements of the schema has been silently ignored on purpose, because they are not mature enough. As ideas,r emarks and
suggestions arise, their purpose will be enlighten.
It should be a good idea to generate a picture of the fully expanded XSD, so as to provide an overview on overall schema.
In order to enclose some release notes information, it is necessary to define a top-level
ReleaseNotes XML element.
The definition, via the XSD
XMLReleaseNotes.xsd structure, is defined in the
xrn XML namespace, which should point to the
http://xmlreleasenotes.free.fr URI. This is the release why you will find the
xmlns:xrn="http://xmlreleasenotes.free.fr" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" prefix on that same XML element. This is the way to identify the namespace.
This XML element contains some mandatory attributes, which are:
ID: the identifier of the component the release notes is being written for,
version: the version of the XRN framework that is supposed to be used. OK, this should maybe be called
XRNVersion, that would be less confusing....
They should be enough in order to identify the component.
Anatomy of a component
Now that we have introduced the top XML element
ReleaseNotes, we can take a closer look at what it contains. All the information enclosed in that XML top element will concern the component
We are going to detail the content of the XML elements that lies under this top element and that constitute the content of
the underlying component.
You can refer to the example on the XRN file that we have already been using.
This element has a single attribute
href that points to an XML file containing the description of the actors involved in the process making of the component. But
let's discard this for the moment, since this is rather a detail at this stage...
Would it not be a good idea to shift that element rather at the bottom if it is not that important at the beginning?
This XML element enables to define the location of other component release notes (the raw ones under XML format, but also
the potentially rendered one, only in HTML for the moment). It is make of
Component XML elements that refer to other components via the
ID attribute (all this seems logical), to their optional XML release notes via the
xml URI attribute, and to their rendered release notes via the
We can understand that this information maybe valuable when we want or need to "cross-reference" components. This will appear more visible when we come to the rendering, but for now, forget it.
DeliveriesThis is a very basic XML element that only owns one URI attribute named
href: this URI will be used as a prefix concerning the location of all delivery artifacts URLs. Don't worry, we'll come to the
concept of artifact very soon...
This XML element expects to contain textual overall description concerning the underlying component. If you already have a
detailed description somewhere else (like in Maven, for instance), there is now use repeating it.
|One important focus the XRN framework is to try not to duplicate information coming from other systems, but rather re-use
in a aggregated manner.
Just provide an accurate description provided your component resides nowhere else, except in a VSC system, that is kind of
pre-requisite (otherwise, why making a release notes framework, if you can't tag your developments).
There, we begin to enter the enter the core of the framework, which, let's remember it, about the notes on component releases.
This part will enclose all the releases that have been or will be performed for the component. A release?
What do we call "release" in fact? There may be various definitions, but for us,
a release is the process of building a component official new version aimed at being distributed
. OK, this is rather loose as a definition, but we do not want to restrict and imprison minds.
Releases XML element just contains
Release XML elements (but that fanciful, OK...). We are going to explain what those
Release elements are about.
|Just keep in mind that the
Release elements should be sorted in a chronological order, the most recent as first element (at the top), the oldest as last element
(at the bottom).
Anatomy of a release
That's time now to declare a release of my component. The obvious thing is that we need to name that release, otherwise, we
would not be able to refer to it in the future. This is declared via the XML element various attributes, that we now exhaustively
version: the information that we have just mentioned.
startDate: the date when the release development has started. This enables to remember when the development has begun, in order to
better evaluate the development time, or at least provide a hint since developers do not always dedicate to the same component
in a serial manner, we all know that!
buildDate: the date the component release is supposed to have been performed. This field is supposed to be updated just before the
release process is started.
deliveryDate: the only use of this field is to indicate a target delivery date for the teams, while the release development has begun
for a new version.
builderID: this is the identifier of the person responsible for the building process of the release. This enables to remember who's
packaged and run the release process of a given version of the component.
Underneath this XML node, we know find some XML elements that provide additional information concerning the release itself.
For the moment, we do not know much about the content of the release.
This section contains all the delivery artifacts yielded for the current version of the component. This is the reason why
it is made of
Delivery direct-child elements, owning a
href attribute, that constitutes the suffix of the URI where the artifact file is supposed to be located at. On its turn, this
Delivery XML element can also contain textual additional information about the delivery artifact (may be a file, a site address, whatever).
|This is the reason why it is important to have one save place where to store all your component delivery artifacts. This place
should be backed-up regularly so as to make sure that you still have a trace of them. This place can be made accessible so
that end-user can directly peek them.
Moreover, this section contains an optional and first-positioned
Summary XML element that is a textual information about the deliveries.
The composition, dependencies and requirements blocks
The next forthcoming XML element have something in common, this is the reason why they are introduced altogether. What kind
of information do they provide?
They indicate precisely the relationships of the component with other components.
Why not then introducing a
Let's focus individually on each of them.
Relations XML element that would encompass them?
Before going any further, you need to know that the
Component element we refer to in the remaining of this section, will refer to a complex XML type that refers to an actual component,
that it owns a
ID string attribute designating its identifier, a
version string attribute indicating what release of the component it refers to.
First of all, be aware that this section only concerns components made of other components, like libraries do. If you are
working on a non reusable component, just forget this.
You do care? OK, this is very simple, this node will contain references to all the components that are delivered in your component.
Imagine that you have designed a library, which is just a collapse of other libraries. In that case, you will declare of those
libraries that are part of the present component.
The element contains a first
Summary element that provides textual overall information about the composition of the release.
This is followed by a list of
Component XML elements that designate the components that are part of the release.
This XML element addresses the need to express that the component depends on other components, when it comes to the development.
This means that this information is not supposed to be interesting for the end-user (even if he is a developer). Nevertheless,
this information is very precious for developers, because it remembers them what their developing environment should contain
in order to develop on it (and not working with it).
As for the
Composition element, you are given a
Summary element in order to explain in a global way what those dependencies are about.
Following that summary, you will find the references of the individual components that are required at development time when
working on the project for contributing on the source code. Just like in the previous composition block, the
Component elements enable to express those dependencies.
This XML element points to the component that are required at runtime, in order for your delivery artifacts to work. This
information is rather dedicated to the end-user: it is often a place where you can overview in one glimpse the environment
that needs to be prepared in order to run the component properly. It is also aimed at helping the production team in charge
with the administration of the component.
The structure is the same as for the dependencies.
Because it would really be too tedious to fulfil those pieces of information for every new release, by default, the blocks
are supposed to be inherited from one release to the next ones. If nothing has changed concerning the composition between
two consecutive versions for instance, you do not want to fulfill the block once again: in that case, do not write this block
at all, it will considered as unchanged. This policy also applies for the dependencies and requirements block.
Most of the time, from one release to the next one, only one component changes or is added, among those expressed in the previous
blocks. The framework naturally contemplates this case. If you need to express that one component version has changed in the
block, you just need to write the block with only this component in it, with the right version. The same thing applies if
one component is being added.
Let's say that in
versionA of your component, you add expressed that it requires - among other requirements - the version
1.0 of a component with an identifier
Required1. If you need to express that in a subsequent release
versionB of that same component, the version
2.0 of the same
Required1 component is required, then you will define a
Requirements block only made of a single
Component XML element with the
ID attribute set to
Required1 and with the
version attribute set to
2.0. The XRN snipset would be.
<Release version="versionA" ...>
<Component ID="Required1" version="1.0">I need version 1.0.</Component>
<Component ID="Required2" version="...">
<Release version="versionB" ...>
<Component ID="Required1" version="2.0">I now need version 2.0.</Component>
This default inheritance feature is transitive, which means that it is being propagated to the later releases.
But now, how would you express that one component has been removed from one the block? This is in order to address this issue
that we have introduced the block 'inherit' Boolean attribute. What is it about?
The 'inherit' Boolean attribute is present in each of the blocks (composition, dependencies, requirements), and its default
true, which means that the previously described inheritance mechanism applies by default. When set to
false on a block for a given release, indicates that the same block defined in earlier releases will not be taken into account
Hence, when you need to indicate that a component is to be removed from a block, set this attribute to
false and re-express exhaustively all the components. This is something that should not occur very often.
As in many places in the XSD, you are given the opportunity to provide an overall description of the release. If you are familiar
with the Doxygen tool, think of this summary as the
brief command. This summary will be used as a synopsis in many places when it comes to the rendering.
So far, we were not able to express what modification, features have been introduced for the current release. At last, we
focus to that part of the release notes.
This XML element just contain
Feature XML elements that will define the features related to the release: we are now going to explain what those "features" are about.
Anatomy of a feature
A "feature"? Whatzaaaaahhh ??? A feature is to be seen as a technical or functional modification of the behavior of the component artifacts.
This feature is supposed to explain what has changed from the previous release.
As a general rule, the XRN framework focuses on the changes from one release to the next one, so that you just have to focus
on those differences.
The aim of XRN is not to standardize the way a feature is expressed, and its aim is not to be a substitute to as needs expression
system. However, we need to be able to indicate what a feature is exactly about in order to render it properly. The
Feature XML element is plenty of attributes that we are going to explain.
|The name and meaning of those attributes are not so clear today, and they may change in the future. However, don't worry,
because XRN is shipped with an integrated migration tool that enables to smoothly use new versions.
When listing the attributes, we'll refer to the notion of actor identifier (the same notion has already been used when we
refered to the release builder identifier vai the
builderID attribute). Moreover, we refer to the
Contributors nested XML elements: their structure are indentical and they only contain
Actor XML elements with a single
ID string attribute that designate an actor once again. They are useful when it is needed to define multiple actors.
ID: this is a string attribute that enables to identify the feature. It has a great impact because you are able to re-use that
identifier for other
Feature elements, provided they contribute to this same conceptual feature. Doing so will gather features through the releases in
the same logical unit, which enables to keep track of the evolution of a feature. We will detail all this when we come to
the explanation of the HTML rendered pages.
type: this is an enumerated string attribute that indicates whether the feature is technical or business.
reason: this enumerated string attribute enables to explain the motivation for the feature addition, modification.
category: this is a free string attribute.
askingPersonID: this string attribute enables to indicate the identifier of the person asking for the feature. If multiple persons are asking
the feature, then use the nested
AskingPersons XML element. Take good care of this field, because it will be used when it comes to filtering, to notification. Whathever,
it's always a good point to remember who has asked for what.
contributorID: this string attribute indicates the person who has contributed for the development of the feature. As for the
askingPersonID, if multiple actors have contributed, use the
Contributors inner XML element. You should always consider fufilling this field with care because it will enable you to remember it who
has done what. Moreover, this will open the possibilities when you need to generated dedicated release notes, when you need
to think about notification. More important, it will provide to the project manager a clear view on who has been working on
what, in order to be able to estimate constraints, making the XRN framework part of a decision making tool.
importance: this integer enumerated attribute enables to range from 1 (less important) to 5 (most important) the weight of the feature.
The default value is at the middle, set to 3. When you need to emphasize certain features compared to to other, augment the
value. At the opposite, when minor features are expressed, decrease the value. Taking care to this attribute will enable you
to filter your release notes when it comes to rendering.
TitleThis XML first direct-child element enables to provide a textual summary title to the feature, which will used when rendering
the release notes.
ItemIn order to be able to describe precisely the feature, you are given
Item XML elements that contain textual descriptions. Use as many as you want in order to articulate your explanations.
You did it!
Well, well, it seems that we have actually reached the end of the explanation concerning the anatomy of a XRN release notes
file. Congratulations if you found the courage to read it all: you will soon be rewarded of your efforts. Because, with those
explanations in mind, we are confident that you better understand what the framework is about.