Xelog file is an XML file that adheres to a structure (described by the Xelog schema) and references view XSL file for the browser to use to show the change log.
I recommend using Xelog template (
xelogTemplate.xml) I have attached to this article. It provides log file for you to customize for your project.
Edit Header
Each XML file has a single root node. Before it we need to specify a view for the browser to use:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="http://www.emeraldhand.com/xelog/views/htmlTable/view.xsl" ?>
1st line is the standard XML declaration. 2nd is a special processing instruction. Browsers recognize it as a reference to the style sheet to transform the XML file with. In this case it references **htmlTable** view on our server.
Edit Root node
The root node is
xelog in http://www.emeraldhand.com/xelog/schema/xelog.xsd namespace.
<xelog xmlns="http://www.emeraldhand.com/xelog/schema/xelog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.emeraldhand.com/xelog/schema/xelog.xsd
http://www.emeraldhand.com/xelog/schema/xelog.xsd">
...
</xelog>
It declares default namespace for all elements and references a schema for this file. Schema reference has two effects:
1. Browser can validate the log file on load and notify user of potential problems with it.
2. Some XML editors support auto-completion if schema is provided. This can help you update the log.
If you're hosting Xelog on your server you might want to change 2nd part of
schemaLocation attribute to point to your copy of the schema and guard yourself from possible changes on our server.
Edit Project node
Xelog file is split into several parts. First section is a
project node describing the project. It holds project name, website link and so on. It's followed by
version sections to describe changes in each release.
<project>
<name>Your project name</name>
<location>ProjectURL</location>
<currentVersion>CurrentVersion</currentVersion>
<issueUrl href="IssuesManagerUrl?bugIDparameter=%ISSUEID%"/>
</project>
| Node name | Description |
| name | Your project name. |
| location | URL to your project's home page. View will usually provide a link to it. |
| currentVersion | Current version for the project. Can be any number, letter, or however you designate versions. |
| issueUrl/@href | URL template to the issues manager (if you use one). Each change can have an ID. Views will generate a link to your issue manager by replacing %ISSUEID% with the actual ID (number or letter, or combination). This should automatically generate links to the issue related to the specific change. |
Edit Version node
You want to create one
version section for each release you make and there can be as many of them as you need.
Here's an example:
<version startdate="2006-07-25" releasedate="2006-07-30" type="release candidate" number="0.1">
<component name="Project component">
<newFeature timestamp="2006-10-13T18:38:13-05:00" impact="5" id="1">
<description>Change short description</description>
<notes>This change affects just one component.
Additional notes on what was changed</notes>
<impactDescription>Notes on how this change affects the user,
how user can benefit from it.</impactDescription>
<author>Author Name</author>
</newFeature>
</component>
<newFeature timestamp="2006-10-13T18:38:14-05:00" impact="5" id="1">
<description>Change short description</description>
<notes>This change affects the whole project (all components).
Additional notes on what was changed</notes>
<impactDescription>Notes on how this change affects the user,
how user can benefit from it.</impactDescription>
<author>Author Name</author>
</newFeature>
</version>
version section is a collection of changes. Each change affects either the whole project (entry is
version child) or just part of it (entry is
component child).
>
| Node name | Description |
|---|
| version | Element representing specific project version. Holds all changes from the previous version. |
| version/@startdate | Date when work on this version started. |
| version/@releasedate | Date when this version was completed. This attribute can be fully omitted to indicate that the version is still under development. |
| version/@type | Type of the release. I'm still working on ideas for this attribute. It will probably change in the future or I might just allow any string. Current possible values are:
closed alpha
open alpha
closed beta
open beta
release candidate
|
| version/@number | Version number. Can by any text. I would advice using numbers separated by dot (.). I.e. 0.1 |
| version/component | Indicates project component. It is used to group all changes specific to a part of the project. |
| version/component/@name | Component name. |
There are several types of possible change entries and they can be either
version child or
component child.
>
| Entry type (node name) | Description |
|---|
| fix | Bug fix. |
| newFeature | A separate new feature that was just added. |
| enhancement | An improvement to some existing feature. |
| task | Some general task. For example refactoring could constitute to the task, depending on how you look at this. In general there should be very few of them. |
All entries have the same structure and are different only by the node name. The following table describes common to all entries attributes and child nodes. Optional nodes are put in square brackets ( [optional] ).
>
| Node name | Description |
|---|
| [@id] | ID of the corresponding issue in the issue manager. This is used to generate link to the issue described online. |
| @timestamp | Date and time (2006-10-13T18:38:14-05:00) when the change was implemented. |
| @impact | Number from 0 to 5 indicating anticipated impact this change will have on the user. 0 is no impact and 5 is a breaking change. |
| [@ref] | Can be used for reference. For example enhancement can reference newFeature to indicate which feature was improved. I'm not really sure if this is useful attribute. I might remove it in the future. |
| [@revision] | Revision number. Originally I intended it to store source control revision number when the change was implemented. In reality I have several problems.
Often change will be implemented over a series of check-ins. Which do you use here?
Next, do you check in the code and then update the change log (and all changes will always be 1 step behind in the source control) or update the change log and then check in (then you don't know revision number for sure).
I'm coming to a conclusion that this attribute in its current state isn't very useful. It's difficult to update and its value is questionable. |
| description | Short change description. Should not be more than one sentence. In reality this is a change title, however when I had title I tended to use 1-2 words and didn't like the result so I switched to description. |
| [notes] | Full description of the change. What was changed, how, and so on. |
| [impactDescription] | This is the text to help the user. It should explain how user experience will be different with the new change and how the user can adjust to it. |
| author | Author name. There can be any number of authors. |