|
From: Ross G. <ro...@sa...> - 2002-11-01 19:36:13
|
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 |