[csms-dev] [Vote] require documentation and tests with all code submissions

[Ross G. <ro...@sa...>]

I mentioned this in a bug report recently, but it probably got lost to 
most people here. This is a very important issue so I am putting it to 
the vote. This is a thing about programming and since there is only 
myself who is a programmer at the moment I would like to encourage the 
few lurkers we have to comment *and* vote on this proposal. Your 
comments will be useful to help non-programmers with voting rights cast 
an informed vote (even if it is an informed abstain). Your vote *will* 
count.

The proposal
============

I believe that the only way to develop Open Source code is to ensure 
that it a) works b) is documented.

To ensure things work we need to have a good set of test harnesses. The 
infrastructure for this is already in place (good old Centipede does 
most of the work for us). More info for those interested can be found at 
http://www.junit.org

Documentation is hated by programmers, it takes time away from coding. 
We already have codestyle checks that ensure all code has at least 
minimal javadoc comments. I propose that in addition we require all code 
submissions that add new features to include at least outline 
documentation about that feature. This need not be technical 
documentation (this is what javadocs are for), but user documentation.

For commiters, this documentation will have to be incorporated into the 
xdocs.

For non-commiters a text file will be sufficient (although patches for 
the xdocs would be more appreciated). The commiter adding the code to 
the repository will be responsible for moving the docs into the xdocs as 
well.

If this is passed I will write these requirements into our constitution.

The reason I think it is important we discuss this is that there is a 
danger that we scare off potential contributors because of the 
additional work.

Whilst this project is at such an early stage it is difficult for people 
to see how they can contribute, but in the not too distant future we 
should be providing something useful, at that point we need to be 
providing a sensible Open Source development that allows everyone to do 
what they need to but isn't quite chaos. The requirement for minimal 
documentation means people can see what is available and so where they 
can help.

There are some lurkers here, I hope some are looking for an opportunity 
to contribute as well as deciding if we are a good bunch to work with. 
I am keen to hear their views as potential commiters.

Ross