[Maria-developers] Documentation for new features
Hi I quite often find out about a new feature after release, either by looking through the changelog and commits, or because someone points out it's missing from the documentation. It's time-consuming trying to keep track of every change, and I miss things (especially in non-default plugins etc), so it'd be better if everyone can remember the need for documentation when adding new features/variables or changes in behaviour. Each task of this sort in JIRA could have a related documentation subtask. You can add to the knowledgebase directly (don't worry about bad English, I will fix), email me with details, or at least alert me about an impending change. thanks, ian
Hi, Ian! On Dec 22, Ian Gilfillan wrote:
Hi
I quite often find out about a new feature after release, either by looking through the changelog and commits, or because someone points out it's missing from the documentation.
It's time-consuming trying to keep track of every change, and I miss things (especially in non-default plugins etc), so it'd be better if everyone can remember the need for documentation when adding new features/variables or changes in behaviour.
I doubt it's possible :( During the release preparation I can look through the changelog and see what needs to be documented. Or we can tweak our workflow in Jira somehow to include documentation. But I wouldn't expect everyone simply to remember the need for documentation all the time. Regards, Sergei Chief Architect MariaDB and security@mariadb.org -- Vote for my Percona Live 2016 talks: https://www.percona.com/live/data-performance-conference-2016/sessions/maria... https://www.percona.com/live/data-performance-conference-2016/sessions/maria...
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On 23/12/15 00:56, Sergei Golubchik wrote:
Hi, Ian!
On Dec 22, Ian Gilfillan wrote:
Hi
I quite often find out about a new feature after release, either by looking through the changelog and commits, or because someone points out it's missing from the documentation.
It's time-consuming trying to keep track of every change, and I miss things (especially in non-default plugins etc), so it'd be better if everyone can remember the need for documentation when adding new features/variables or changes in behaviour.
I doubt it's possible :(
During the release preparation I can look through the changelog and see what needs to be documented.
Or we can tweak our workflow in Jira somehow to include documentation.
This sounds reasonable. Might just hint to developers "oh that's right I added a variable X" or "its important to note Y in the release notes" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQEcBAEBCAAGBQJWiMMvAAoJEMXeEgVQ15xMba4H/1Odo4j0SH/af9log3r/D2HZ aFDhf0Cr1YFSd+prSJB33BEHghSFgsPvkFz/8bGAdG7yxtHoPK8BjzZdIedMHGi1 DCxsp0qYFk44xAKnz3f8D2fp7ff9nWSL1HzZAncjXLRLpL13VN8/oetIA8N5CPHK tmZQ0w/TsbWmybS3V2F0cO39LT77cwxIsZ9q8lbbATuojjUrYKXqj+WIP/tXue8H w2mDpeRUfyoCISiX9DNoyjuw7b8hIqL7smZOb8aYRGQu9Gfm8NCL/uYzll0FxKHU tXJ61LkBFlB3FdlIDY3V2B9stxJFUxcArUKjIKH1uUBNzynJWCKhQ9fZxXpHhlE= =Zw5d -----END PGP SIGNATURE-----
On 22 Dec 2015, at 21:56, Sergei Golubchik <serg@mariadb.org> wrote:
Or we can tweak our workflow in Jira somehow to include documentation.
Don’t close a Jira until after it has passed to documentation. So, once a task is complete, it should go to the “documenting” stage. IIRC, this is how MySQL does it in bugs.mysql.com. There is a status called “documenting” I do see the “problem” during release phases, but I’m sure we could filter out completed Jira’s in the documenting stage (then again, the MariaDB Server project shouldn’t release anything that is undocumented; so does this then, delay the release?) -- Colin Charles, http://bytebot.net/blog/ twitter: @bytebot | skype: colincharles "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi
Hi, Colin! On Jan 03, Colin Charles wrote:
On 22 Dec 2015, at 21:56, Sergei Golubchik <serg@mariadb.org> wrote:
Or we can tweak our workflow in Jira somehow to include documentation.
Don’t close a Jira until after it has passed to documentation. So, once a task is complete, it should go to the “documenting” stage.
Is an issue "fixed" if it's in the "Documenting" step? I mean, from the Jira point of view. When an issue becomes "fixed", it must have the correct FixVersion (say, 10.1.10, not 10.1), a Component, and a Resolution (say, "Fixed" or "Not a Bug"). Workflow ensures that all this is set in all fixed issues. Logically, as soon as an issue is pushed, it's fixed - at least, FixVersion, Component, Resolution are known at this point. And if a release is made when an issue is in the "Documenting" step - the issue will be in the release, right? So FixVersion *must* be set when an issue is pushed.
I do see the “problem” during release phases, but I’m sure we could filter out completed Jira’s in the "Documenting" stage (then again, the MariaDB Server project shouldn’t release anything that is undocumented; so does this then, delay the release?)
There's very little that can delay our release nowadays. And issues in the "Documenting" step are certainly not it. I think it's possible to create a workflow where a developer cannot close an issue, but can only set it to "Documenting" and Ian is the only one who can move from "Documenting" to "Closed". And Jira treats "Documenting" issues as fixed. But then Ian will be a single person who can close issues (not talking about Incompete, Not a Bug, etc). Is that reasonable? Too much work for him, and single person will be a bottleneck. A less extreme option would be to have the above workflow only for Tasks, but not for Bugs. Regards, Sergei Chief Architect MariaDB and security@mariadb.org -- Vote for my Percona Live 2016 talks: https://www.percona.com/live/data-performance-conference-2016/sessions/maria... https://www.percona.com/live/data-performance-conference-2016/sessions/maria...
participants (4)
-
Colin Charles -
Daniel Black -
Ian Gilfillan -
Sergei Golubchik