Undertanding the XRN schema

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 enough...

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.

Important:

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.

Warning:

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 useful.

Definition of a release notes

Important:

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.

Important:

You will find in may places the ContentType XSD complex type definition. Just consider that this type enables to provide textual information.

Warning:

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.

Note:

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.

Note:

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 referred to.

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.

Note:

You can refer to the example on the XRN file that we have already been using.

Actors

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...

Note:

Would it not be a good idea to shift that element rather at the bottom if it is not that important at the beginning?

Components

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 href attribute.

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.

Deliveries

Summary

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.

Important:

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).

Releases

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.

This Releases XML element just contains Release XML elements (but that fanciful, OK...). We are going to explain what those Release elements are about.

Important:

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 present.

• 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.

Deliveries

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).

Important:

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.

Note:

Why not then introducing a Relations XML element that would encompass them?

Note:

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.

Composition

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.

Dependencies

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.

Requirements

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.

Inheritance

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.

Example:

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.

<Releases>
	...
	<Release version="versionA" ...>
		<Requirements>
			<Component ID="Required1" version="1.0">I need version 1.0.</Component>
			<Component ID="Required2" version="...">
			...
		</Requirements>
		...
	</Release>
	<Release version="versionB" ...>
		<Requirements>
			<Component ID="Required1" version="2.0">I now need version 2.0.</Component>
		</Requirements>
		...
	</Release>
	...
</Releases>

Note:

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 value is 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 at all.

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.

Summary

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.

Features

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.

Note:

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.

Attributes

Warning:

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.

Note:

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 AskingPersons and 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.

Title

Item

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.