Hi Paul, First of all thank you very much for all the work you did for Koha 3.10. I think it is a good idea to streamline the bug descriptions in a way that they can directly be used for documentation purposes. My first idea would be to use comment #0 as well. Drawback is that comments can not be edited (afaik). The first wording might not be as precise as it should be to serve as a good description. And the behaviour of the patch / enhancement could change during the bug process. My proposition is to add an extra text field (Large Text Box) below the new Patch complexity field. Name could be "Description for documentation" to make clear that it will be used afterwards. There could even be a link to the Wiki to explain what we expect in this field. And there could even be a rule to set a bug to "Failed QA" if this field is not properly used. The documentation process then could 'harvest' this field. I attach a screen shot as illustration. What do you think about? Marc Am 27.11.2012 18:20, schrieb Paul Poulain:
Hi koha-devel,
As you've all seen, I made a huge effort to have nice and complete description of 3.10.0 enhancement. I partly used some tools for that, and partly made it manually.
It would be much much much easier for the next releases if patch submitters could do better descriptions, (in either bugzilla description/comment #0 or patch itself)
Here is an example of something that we should avoid: * "this patch add a system preference to manage this and that" => OK, but which syspref ??? (I also see things like "this patch add a permission ...", "add an authorized value ...", "add some styling to ...") * it's uncomfortable to have sometimes the description of the bad/incomplete behaviour, and sometimes the description of the expected behaviour. I think we should always have "Without this patch, Koha /would do this and those, that are wrong|used to do this and that/, with this patch, Koha will do <this and that>" * use "I"= there is sometime "I propose to add this" or "I fix this..." We should prefer neutral terms instead ("This patch add this") * There is also an inconsistency, sometimes the submitter write "There should be this/it would be useful", sometimes "This patch adds this", sometimes some other way of starting the description. The worst option, that I saw sometimes is when it's written in a way one can't understand what is the wrong behaviour and what is the new one ! In my document, I’ve usually written "This patch do this and that". I think we should promote a standard way of writing ("this patch do this and that" or anything else).
Anyone has an idea for improving what could be in our coding guidelines ?
