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