[Koha-devel] Some suggestions for patch descriptions

[Marc Véron]

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 ?
>
>
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PropositionNewBugDocumentationField.jpg
Type: image/jpeg
Size: 97356 bytes
Desc: not available
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20121127/0d054e5c/attachment-0001.jpg>