Documenting user visible changes

Documenting user visible changes

[Loic Dachary]

[-- Attachment #1: Type: text/plain, Size: 1291 bytes --]

Hi Ceph,

It would be nice if the description of an issue contained a paragraph documenting user visible changes, when relevant. They could be conveniently linked from the release notes. 

Although it could be done when backporting or preparing the release notes, it's a significant amount of work, reason why it has not been done for all issues so far. I tried on an issue I know well:

   http://tracker.ceph.com/issues/9665#User-description

and another I did not know anything about:

   http://tracker.ceph.com/issues/6228#User-description

Although Alistair proofread it and said http://tracker.ceph.com/issues/6228#User-description improves his understanding of the problem and the solution, it took me a long time to write and I don't find it particularly clear or well written. The next step would be to have it reviewed by someone else and improve. I'd be happy to do it as part of the backport work, to help developers who did not have time or forgot about it. But I suspect that if we have to do it for all issues it won't work because it's too much work.

I'm cc'ing Neil because he made me realize how important it is to have user visible changes properly documented.

Any idea you may have are very welcome :-)

-- 
Loïc Dachary, Artisan Logiciel Libre


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]