I've been working on getting CloudStack's legal documentation in order for the project's first official Apache release, and I have to say that it's been fantastic to use Apache Whisker for this work. Whisker is a project aimed at helping people do exactly what I was doing for CloudStack: documenting all of the source code and binaries for a large open source project. Whisker hasn't officially released yet, but I've found that the source code is easy to navigate and the documentation is already very good.
Whisker let's you write an XML file to declare the various entities that are part of managing your licensing, including licenses themselves (including template syntax for replacement variables), organisations (and people), notice files, and finally... defining how the project artifacts relate to the other elements. You can see the CloudStack descriptor.xml file in our git repo, and the resulting LICENSE and NOTICE files. Without Whisker, I really would have lost my mind creating 4,118 lines of LICENSE file fun, and the cooresponding 659 lines of NOTICE file content (and we're not entierly done with our audits yet).
Knowing that I've been an early user of the project, I certainly expected to have to sort through a few bugs. I'll be submitting patches back to the project next week, but for now I'll just explain some of the issues that I've run into (and how I worked around it).
S instead of Z
The XML syntax for whisker expects "organization" to be spelled "organisation" (with an S, not with a Z like the US spelling of that word). As someone who defaults to en-US in my head, that one threw me for a loop! It was a minor problem, but I spent several hours trying to figure out if there was a bug somewhere in the code. Hopefully that gets added to the project's FAQ for those of us that like the sound of our Z's.
I had to make a few tweaks to the default LICENSE file template to get all of the relationships I had modelled correctly displaying. This is one that I'll try to send into the project, but here are the changes that I had to make:
svn diff apache-whisker-velocity/src/main/resources/org/apache/creadur/whisker/template/velocity/license.vm Index: apache-whisker-velocity/src/main/resources/org/apache/creadur/whisker/template/velocity/license.vm =================================================================== --- apache-whisker-velocity/src/main/resources/org/apache/creadur/whisker/template/velocity/license.vm (revision 1373827) +++ apache-whisker-velocity/src/main/resources/org/apache/creadur/whisker/template/velocity/license.vm (working copy) @@ -29,6 +29,7 @@ #end #foreach( $directory in $work.Contents ) #if (! $work.isOnlyPrimary( $directory ) ) + Within the $directory.Name directory #if ( ! $directory.PublicDomain.isEmpty() ) placed in the public domain @@ -44,20 +45,18 @@ #end #foreach( $license in $directory.Licenses) -#if (! $work.isOnlyPrimary( $license) ) licensed under the $license.Name#if ($license.URL) $license.URL #end#if( $work.isPrimary( $license.License )) (as above) + $license.CopyrightNotice #else (as follows) $indent.indent(12,$license.CopyrightNotice) $indent.indent(12, $license.Text) #end #foreach( $organisation in $license.Organisations) -#if ( !$work.isPrimary( $organisation )) - from $organisation.Name #if ($organisation.URL) $organisation.URL #end - + from $organisation.Name #if ($organisation.URL) $organisation.URL #foreach( $resource in $organisation.Resources) - $resource.Name + $resource.Name #if ($resource.Source) $resource.Source #end + #end #end -#end #end #end
Command Line Features aren't as good as the Maven Plugin
The project supports a CLI-based approach to using it, but I struggled with that a bit. I've already sent in a patch to help with using the CLI interface (which was accepted and is in HEAD for the project now). There's one other issue that I haven't had time to work out: the CLI only puts the results of the LICENSE file into standard out, and doesn't show the NOTICE file content that you would expect (and I needed). To solve this one, I temporarily swap the contents of apache-whisker-velocity/src/main/resources/org/apache/creadur/whisker/template/velocity/license.vm with the contents of notice.vm (and then re-run the command). That seems to do the trick for me (although I'll see if I can find that issue for the Whisker team).
I'm looking forward to Whisker releasing it's first version. The project team has done a great job, and I expect that it will be adopted by lots of F/LOSS projects!