[Koha-devel] Some suggestions for patch descriptions

[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 ?



-- 
Paul POULAIN - BibLibre
http://www.biblibre.com
Free & Open Source Softwares for libraries
Koha, Drupal, Piwik, Jasper