Documentation: Server Configuration Completed

I have now finished migrating the configuration documentation for the server into the code base. This means all the values for the server configuration are documented (although sometimes not well). This also included adding any missing documentation and ensuring everything is in a consistent format.

So take a look and leave a comment in the documentation if you notice anything that should be corrected.

Note: Do NOT leave comments about bugs or issues in the documentation! We do not read these very often. If you need to log a bug, please use either the mailing lists (see http://confluence.public.thoughtworks.org/display/CCNET/Mailing+Lists) or JIRA (see http://confluence.public.thoughtworks.org/display/CCNET/Issues).

And yes, I know people will ignore the note, deleting comments gives me something nice and easy to do

CruiseControl.NET XSD – Second Attempt

A long time ago I tried to write an XSD for CruiseControl.NET. This used an old-fashion technique: copy-and-paste. I literally went through the entire documentation and copied and pasted all the configuration elements.

Now this schema had a large number of errors in it for the following reasons:

• Copy-and-paste is only as good as the copy-paster doing the work
• The documentation was missing a number of elements or was invalid
• I didn’t fully understand how NetReflector worked
• I didn’t fully understand how XSD worked
• No documentation was copied

At the time it worked for me, so I was reasonably happy, but it was something that always stuck around in the back of my mind.

Now, a number of things have improved since my first attempt. I’m now the “owner” of NetReflector and I’ve spent some (serious) time understanding how it works. I’ve also done a lot more work with XSDs and figured out a number of new things (well old to those who understand XSDs). And finally, I’m in the process of going through and updating the documentation!

Anyway, part of doing the documentation involves generating examples where these are missing. Normally my process was to write the configuration by hand, and then run it through the validator. To find out what I wanted, I would look in the code and then build a minimal example. For the full example I would normally copy the “processed” element from the validator.

Now this guaranteed that I had working examples, but it involved a lot of to’ing and fro’ing, especially for the larger examples. That’s when I remember XSDs and intellisense in Visual Studio.

So, I have modified the documentation generator to also generate XSDs for the elements. That’s the good news, now for the issues. First and foremost, it is impossible to completely generate the XSD from the code base. I know, I tried, really, really hard – and still I couldn’t get it working – at least not without some serious changes to how NetReflector works (there are just too many areas where it was impossible to find out what was happening by code!)

So the documentation generator generates a 80% solution. It generates one XSD per configuration element and I then go through and complete the remaining 20%. Once the element has been completed I merge it into the main XSD – which is currently around 200Kb (it’s big and getting bigger!)

The second issue is how NetReflector works. If the data type is a primitive type (e.g. int, double, boolean, etc.) or a string, NetReflector does not care whether it is an element or an attribute. So to be 100% correct the XSD would have to handle this scenario. But, if both an attribute and an element of the same type is added (or multiple elements of the same type) NetReflector will throw an exception! So the XSD would have to except either an attribute or an element – and I have no idea how to do that.

So to simplify things, most properties are defined as elements, even though they can also be attributes. There are a few exceptions, but these I have changed by name (and thus may be lost in future).

With these two limitations the XSD generation and the XSD itself is working I have added all the tasks/publishers, triggers and related configuration – basically everything that I have imported into the code base. As I update the documentation I will also update the XSD.

In a future post I’ll talk about where I’m planning on taking the XSD and configuration in general for CruiseControl.NET, but for now, it’s time to finish the documentation!

To finish with, here are a couple of examples of the XSD in action (this is using Visual Studio 2008):

Of course, I’ll finish by mentioning that this is still a work in progress, but soon it will cover the entire “core” configuration.

Stay tuned…

Security Documentation

A while ago I wrote about some scenarios for security. These were written as I was in the process of implementing security for CruiseControl.NET, so they were up-to-date at the time.

However, as I neared completion of security, I realised some things were not as clear as they should have been, so I changed a few things. These changes unfortunately broke the scenarios – in that the configuration that was produced was no longer correct

Now, as part of the drive to update the documentation for CruiseControl.NET, I have revised and corrected these scenarios. Each scenario is based around a fictitious company or project and goes through the whole process of designing and implementing the security for that scenario.

They were designed to give an overview of what can be done with security, although they don’t cover all the possible scenarios (feel free to provide some more examples and I’ll write them).

Anyway, here are the updated scenarios:

• Small In-house Development Team
• Large In-house Development Team
• Open Source Project

Hopefully these will help in implementing security for CruiseControl.NET.

Documentation: Slow progress

As I recently posted, I’ve taken on the job of reviewing the documentation for CruiseControl.NET. We actually have a LOT of documentation, although from some of the comments I’ve seen we don’t always hit the mark.

At the moment I am working on the documentation for configuring the server – since this is where most people go initially. I am moving all the current comments from the wiki into the codebase as doc-comments, so hopefully in future other developers will see these and realise that they need to add documentation! But as you might realise, it takes time to import the documentation, generate the documentation, check it, fix any issues, re-generate it, check it, fix more issues, etc., etc.

Currently I have finished almost half the documentation (triggers, tasks/publishers, dynamic values) – although there is no end in sight yet! Once I’ve finished the server configuration, I’ll do the dashboard configuration (since that will be a similar process) and then take a break

So, feel free to take a look at the new documentation. Let me know if there are any errors, or anything that could be added to make things clearer.

Happy reading…

Documentation Update

Over the past few days I have been slowly moving the documentation into the code base so the automatic document generator can work. I have now managed to migrate all the tasks, publishers, triggers and related configuration, plus I have published the resulting documentation on the wiki.

Please take a look and see if there are any issues. Otherwise, I will continue slowly working my way through the documentation (source control blocks are next)…

Documentation: Some Nuts and Bolts

Previously I wrote about how I’ve been changing the documentation in CruiseControl.NET so it is now inline with the code. In my last post on the topic (read it here) I talked about the changes to the code base to allow automatic code generation. The next question is how to actually generate the documentation?

First and foremost, the code needs to be compiled. This will generate the dll, a pdb file and (now) an xml file. The first file is the actual binary, the second is the debug information and the third is all the document comments from the code base. Of these three files the documentation generator uses the binary and the xml.

Additionally, projects can have dependencies on other projects that contain information necessary for documentation. As an example the core project has a dependency on the remote project. This project contains definitions for many types which can be part of the configuration. Therefore, in order to generate the documentation, these files are needed as well.

So for the core project, the files that are needed are:

• ThoughtWorks.CruiseControl.Core.dll
• ThoughtWorks.CruiseControl.Core.XML
• ThoughtWorks.CruiseControl.Remote.dll
• ThoughtWorks.CruiseControl.Remote.xml

The good news, if you build the solution these files will all be automatically generated

Next, there is a new project added to the tools folder called docGenerator (a nice simple name!) At the moment this is a C# project, only the source code is in Subversion. So the next step is to compile this project. Once this has finished, the documentation can be generated.

Note: docGenerator only needs to be rebuild if there are any changes to its code. Otherwise this step can be skipped.

docGenerator is a command-line tool. It has one required parameter – the assembly to document, and one optional parameter – the output location. If the output location is omitted the wiki files will be put in a time stamped directory underneath the current directory.

For example, here is how I run it:

This generates a set of files into C:\Temp\output:

Each of these files is a plain text file containing the wiki mark-up:

From here it is a simple matter of copying and pasting into the wiki – and making sure everything looks ok

Documentation – a Sprinkle of This, a Dash of That

In my last post (read it here) I showed the results of a new documentation process for CruiseControl.NET. The aim was to move the documentation from being split over two different locations (code and the wiki) into one (the code) and to make it easier for developers to write documentation (plus it also standardises the documentation!)

To do this I have used doc comments in the code (yes it bloats the code, but with Visual Studio these comments can be collapsed). Most of the time I tried to use the standard documentation tags (e.g. summary, remarks, example, etc.), but unfortunately the standard tags don’t cover all we need

The good news is when Microsoft wrote the doc comment extraction application they didn’t enforce the tag types. This means we can add additional tags and they will happily be extracted. Of course, we don’t want to go overboard as the intellisense in Visual Studio doesn’t know about them (does anyone know of how to add new doc comment tags to Visual Studio?)

The new tags I have added for classes are:

Tag Name	Description
title	An optional title for the item – otherwise it will default to the name in the ReflectorType attribute.
version	The version that this is available from.

The new tags I have added for fields and properties are:

Tag Name	Description
default	The default value if this element is omitted.
version	The version that this is available from.

Additionally I expanded the code tag (this already exists) to have a title attribute. This will apply the title to the code example block – Confluence allows code titles, so it nicely ties the two together.

The documentation generator mainly uses reflection for the documentation. However this generates the bare bones of each article. For example, this is what the state element looks like:

This is because this class has no doc comments (none at all!) associated with either the class or the fields/properties that are reflected.

Adding the summary tag adds the description:

Adding a title tag:

And a version tag (this was a guess):

Finally, to add an example I used the example tag (with the new title attribute):

Finally the configuration element data is added by adding the default and version tags to the actual property definition:

Notice how this was a progressive enhancement of the documentation. If we added a remarks tag to the class documentation we would get a notes section (this element doesn’t have any notes at the moment).

The doc comments for the class look like this:

/// <summary>
/// The File State Manager is a State Manager that saves the state for one project to a file. The
/// filename should be stored in either the working directory for the project or in the explicitly
/// specified directory. The filename will match the project name, but will have the extension .state.
/// </summary>
/// <title>File State Manager</title>
/// <version>1.0</version>
/// <example>
/// <code title="Minimalist example">
/// &lt;state type="state" /&gt;
/// </code>
/// <code title="Full example">
/// &lt;state type="state" directory="C:\CCNetState" /&gt;
/// </code>
/// </example>
[ReflectorType("state")]
public class FileStateManager : IStateManager

And for the property:

/// <summary>
/// The directory to save the state file to.
/// </summary>
/// <version>1.0</version>
/// <default>The directory CCNet was launched from.</default>
[ReflectorProperty("directory", Required=false)]
public string StateFileDirectory

Where possible the document generator pulls the data from the attributes and property definition. For everything it tries to find the relevant doc comments – leaving them empty/blank if not found.

What do you think so far?

I’ll do one more post – how the document generator works from an external viewpoint, and how to get the documentation into the wiki.

Documentation – The Developer has Gone Mad!

Yes, it didn’t take me very long

In my last post (here) I said I was going to go through all the documentation and ensure that it is:

1. Up to date
2. Valid
3. Standardised

For the first step in this task I generated a list of all the types in the Remote, Core and WebDashboard projects that had the ReflectionType attribute (this means a type can be used in the configuration).

This identified 176 classes that needed to be checked. Now not all of these classes are used as tasks, triggers, source control blocks, plug-ins, etc., some are ancillary types to provide sub-information (e.g. named values, user details, etc.)

This data was dumped into an Excel spreadsheet, so I could go through each and every class to check the documentation. As you might have guessed, this didn’t last very long…

The first class I checked was DefaultQueueConfiguration – which maps to the queue tag. Now, as classes go, this one is fairly simple – only three properties that are reflected. But, after half an hour of flicking backwards and forwards between the documentation and the code I was thinking why do we have the data split over two places?

Instead I copied all of the documentation from the wiki into the code as doc comments (including some reformatting). This means everything is in one place now – yay!!! However, this doesn’t answer the problem of documentation – it just means duplication of data

So, rather than do more documentation I quickly put together a little application that used the XML comments and reflection to automatically generate the documentation. Now the code is back to being the single source of truth, plus the documentation will now be more consistent (since it is automatically generated).

Here are some before and after shoots of how the documentation looks (they are big, so click on the thumbnail to see the full version):

Now I am back to the process of reviewing documentation – in a future post I explain how the process works and what is required.

Documentation (or How to Overload the Developer)

As part of the preparation for the 1.5 release (hopefully soon) I thought I’d go through and review the documentation to ensure it is:

1. Up to date
2. Valid
3. Standardised

All the documentation for CruiseControl.NET is stored at http://confluence.public.thoughtworks.org/display/CCNET. This is an online wiki with its own formatting mark-up (it uses Confluence).

Now, the question arises of how to review the documentation?

For CruiseControl.NET the source of truth is the code, so I need to go through both the documentation and the code to ensure everything matches. What would be really nice is if everything was documented in the code – but I won’t comment on what our documentation comments are like.

So, that leaves a nice challenge of checking everything manually.

Basically, I’m planning on doing it two ways. First, I will go through the code and verify all the items in the documentation. Hopefully this will cover most of the pages in the wiki. Once I’ve done that I will then go through the remaining pages and check them.

Now for the bad news, I’ve extracted all the classes in CruiseControl.NET (from the Core, Remote and WebDashboard assemblies) and there are 176 classes that can be reflected – which means 176 classes that can be included in the documentation.

So, this may take some time…

Notes: As a side task I am also planning on importing the documentation from the wiki to the code. This means in future we should be able to automatically verify some of the documentation (hopefully!)

Documentation Has Arrived

Some New Stuff, Some Old Stuff

Like any system, documentation is an important part of CruiseControl.NET. With the 1.5.0 release, we’re adding a lot of new functionality – all of which needs documentation. So I’ve taken some time out of resolving issues and adding code coverage to document some of the new things that are coming.

As well as documenting the new stuff, I’ve also been updating some of the older documentation, although this is mainly around adding what has changed. Some of our changes has had a major effect on all the tasks and publishers. But I’ve tried to also add some value to the documentation around versioning.

Finally, I’ve also been trying to add some more contextual documentation. A large part of the current documentation describes the various configuration options, and what can be set. We also have some stuff on using the system, including with other tools and components, and a little bit of development documentation. Basically, I’m trying to fill out the last two sections a bit more!

What’s New?

We have lots of new stuff for 1.5.0, some of which has been requested for years! In terms of configurable items, we have added the following:

• Security (big change)
• Dynamic values and parameters (wide-ranging change)
• New tasks and publishers (parallel, sequential, conditional, NCover, PowerShell and FTP)
• New source control providers (RoboCopy, VSTS, FTP, Git and Mercurial)

Most of which have now been documented (just the RoboCopy and VSTS source control blocks outstanding).

Before I move on, a quick comment on the security. This is a very big change, and one that has a lot of associated documentation. I’ve gone through and added the basics on all the configuration options, but as Ruben pointed out, the sheer volume of configuration for this area can make things very confusing. As such, I’ll be going through and adding more over time.

What’s Updating?

One of the widest-ranging changes is the additional of dynamic parameters. Nearly every single task and publisher can use them! As such I’ve gone through and added this to all the tasks and publishers that can use them.

Additionally, we have an issue where we have only one documentation wiki – which has to handle all versions of CruiseControl.NET. To try and make sense of what works in various versions, I have added two additional items.

First, all new items have a Version section. This section says when the item was first added (e.g. 1.4.4, 1.5.0, etc.) This should help people who want to try a new item, but they are still using an older version. Of course, there are a huge number of items that have been around for a long time – these I have not documented. Basically, if there no Version section, then it will work in 1.4.0, not sure about older versions!

Second, to the configuration elements table I have added a Version column. This works in the same way as the Version section, it says when the element was first added. Again, since there is a lot of old stuff, not everything will have a version number. Perhaps if I am bored one day…

What’s Contextual?

Since both security and dynamic values and parameters are new, I have tried to explain what they are for, how they work and what some of the possibilities are. For security, I’ve started adding some scenarios of how it can be used. Actually, at the moment there is only one, but there are two others in this blog that I need to update and migrate over.

Finally, I’ve also started writing about how security can be extended. When I designed it, I added all sorts of interfaces for different things. So, if you don’t like what I have done, it should be easy enough to swap out a part and use your own implementation.

What’s Missing?

While I’ve added a lot to the documentation, I don’t consider it anywhere near finished yet!!! here are some of the things I would like to see done around documentation:

• Review everything: a lot of the configuration documentation is inconsistent – not surprising considering the number of people who have worked on it over time – it would be nice to go through and put together a consistent style (e.g. what is included, etc.) through the entire documentation.
• Client apps: there is some documentation on these, but a lot of it is out of date, especially considering the number of things that have changed.
• Developer documentation: my first few months on CruiseControl.NET was just trying to figure out what is what, heck, even now I am still confused at times!

Anyway, these are just my thoughts, at least we have some documentation!!!

So, in closing, please take a look at some of the new documentation and let me know what you think. As always, I’m too close to the trees to see the forest