https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 David Nind <david@davidnind.com> changed: What |Removed |Added ---------------------------------------------------------------------------- QA Contact|testopia@bugs.koha-communit | |y.org | Status|NEW |ASSIGNED Priority|P5 - low |P1 - high Assignee|koha-bugs@lists.koha-commun |david@davidnind.com |ity.org | CC| |aude.charillon@ptfs-europe. | |com, bwsdonna@gmail.com, | |caroline.cyr-la-rose@inlibr | |o.com, | |lucy.vaux-harvey@ptfs-europ | |e.com, | |martin.renvoize@ptfs-europe | |.com --- Comment #1 from David Nind <david@davidnind.com> --- Message from Martin Renvoize on 16 June 2022 (hope you don't mind me adding this here...): "I was chatting to our staff today and they're still keen to contribute to the manual, but are also still finding the process confusing especially with regards to choosing area's to document and when. I came up with a proposal a little whilst ago to try and integrate the process more into the other community processes and bugzilla. Would it be helpful/useful to add a 'Ready for documenting' status in Bugzilla that sits between 'Pushed to X' and 'Resolved Fixed' and encouraging the Release maintainers to use that when they make the decision to not backport instead of the current 'Resolved fixed' change. This would allow for building a queue automatically on dashboard.koha-community.org for documentors to work through much like the testers and the QA team do. So one would look at the list, work on docs submissions and then update the bugzilla status to 'resolved' upon completion (or upon making the decision that documentation updates are not needed)? Just a thought.. I'm happy to do the bugzilla admin changes and update the dashboard. What do you think?" -- You are receiving this mail because: You are watching all bug changes. You are the assignee for the bug.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #3 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- (In reply to David Nind from comment #2)

1. Would it be possible to have a 'Documentation Contact' field, like there is for the QA Contact. That would mean the team (or anyone) can assign themselves to the documentation task.

I love the idea of a 'Docs Contact' field. I can certainly add one, but I can't link it to users the same way 'QA Contact' works :(. (I'll submit a bug upstream to the bugzilla devs for this, I've often found myself wanting that)

2. How would this work with the current developer work flow: release manager pushes to master, release maintainers push to their versions - who changes to "Needs Documentation" (documentation manager?) - after the documentation changes are made, do we need another status like "Documentation Updated" - who would change to "RESOLVED FIXED" (is this changed at the end of the release cycle, or continuously once pushed to a maintenance release?)

The guidance right now is for Release Manager to use 'Pushed to master', then the Release Maintainers watch for that and as the backport they use 'Pushed to X' and if they make the decision not to backport then use 'Resolved Fixed'. My proposal is that the Release Maintainers simply switch from using 'Resolved Fixed' to 'Needs Documenating' as they're 'Final status'.

2. Decide if documentation updates are required (bugzilla status = Needs Documentation) (anyone, Documentation manager - review pushed bugs regularly)

I was thinking lets spread the load for this decision. Rather than requiring the docs manager to review all bugs, we produce a list of the dashboard using the new status and docs team members work through the said list marking themselves as 'Docs contact' and updating the status to the next step as appropriate (which may well be a simple switch straight to 'Resolved fixed' when they deem a bug doesn't actually need any documentation changes)

6. Once documentation updated, status changed to 'Documentation Updated' (not sure on this step - but it would be nice to have something like Signed Off - [Month/Year] on the dashboard) ...repeat until there are no more documentation tasks!..

I had only envisaged adding 'Needs documenting' or similar, but we could easily track progress with an additional state.. so 'Pushed to X' -> 'Needs documenting' -> [ 'Resolved fixed' | 'Documentation submitted' ] -> 'Resolved fixed' Adding the 'Documentation submitted' option would allow for the docs manager to have a list to work through in a similar fashion to the QA team's todo list (though simply having gitlab submissions may serve the same purpose for the Docs manager.. so I'm not sure how helpful it is?)

I had thought about using a third party tool, like Trello, or go back to Taiga.io, or use the issues tool in GitLab (my second preferred option over using Bugzilla) - but having one tool, and not needing to manually duplicate or maintain something else is the ideal.

I'm not at all against third party tools (and I'm not always the biggest fan of Bugzilla.. I'm just thinking that folding it in to the existing infrastructure may make things clearer to the wider community and userbase maybe? I'm also all for automating or making things second nature process-wise rather than burdening anyone individual with a maintenance task.. maintaining an external tool is always difficult.. bugzilla has served as a pretty nice central place for data so if we can bend it to our will here and just use the info that's already in it I think that's a step forwards.

Anyway, thoughts welcome! (And thanks Martin for starting the discussion!)

It's been a pleasure.. I'm always open to discussions and trying to help move processes forward.

Will add to the next documentation team meeting agenda to confirm anything we decide from this discussion.

Excellent. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 Martin Renvoize <martin.renvoize@ptfs-europe.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |arthur.suzuki@biblibre.com, | |lucas@bywatersolutions.com -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #5 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- OK, I've had a go at implimenting a first draft of this.. we now have a 'Needs documenting' status between 'Pushed to X' and 'Resolved' in bugzilla and I've updated https://dashboard.koha-community.org/ to display this new state in the 'To Do' area and under 'Bug statuses'. Obviously, the status is not yet set for any bugs at the moment; thus, the lists are empty... but it should give an idea of how it would look and give people a clear way to get started on picking what to document. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #7 from Katrin Fischer <katrin.fischer@bsz-bw.de> --- Hi all, +1 for the general idea, thx Martin for bringing this up! +1 for having the RMaints set the status. Spread the burden is really key I think. I am not sure about a 'documentation submitted' status - I think maybe posting a note with the gitlab merge request + setting to RESOLVED might suffice? Every click less is usually helpful. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #9 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- I've added a 'Documentation contact' customer field.. though it can't be linked to bugzilla users so we'll have to hope people just type their name in consistently (I was going to use it for the leaderboard sections of the dashboard if your interested and motivated by that sort of thing) I've also re-enabled the 'Documentation submission' custom field which we introduced a while back but never really took off.. we could use that for gitlab merge request links.. but I'm not sure if that's adding burden to the process or is helpful?.. it could signify a submission has taken place in the bugzilla world to give us something to bind on for the dashboard again... jury's out.. let's see how this feels to start with. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #11 from Katrin Fischer <katrin.fischer@bsz-bw.de> --- A link field might be useful, but might be better linking to the section in the manual... but then you might have changed multiple pages. Not sure on that one yet. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #13 from David Nind <david@davidnind.com> --- (In reply to Martin Renvoize from comment #10)

Regarding back populating, perhaps we should work on a report or if you have a spreadsheet already, use that to do a bulk update? (With Chris disabling email to not spam the world too much)

I'm also wondering if we could just draw a line and work through old things via your existing sheets and use this workflow for moving forward?

It makes much more sense not to spam everyone, was thinking they might not appreciate all the email in their inbox! I'll get my lists up to date for the current release, 22.05, 21.11 and 20.05, then we can look at. Definitely, we should do for 22.11. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #15 from Arthur Suzuki <arthur.suzuki@biblibre.com> --- Just my 2 cents here. Isn't the devs who provides code at the best place to know exactly what the code is doing or how it changes its behavior? and therefore documenting it? Just like it is now mandatory to provides unit tests and test plans in the commit message, we could make a documentation mandatory for an enhancement or big change to reach Koha Community code. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #17 from Victor Grousset/tuxayo <victor@tuxayo.net> --- Directly on topic for this ticket: we need in bugzilla to not be able to choose "push to oldoldstable" because the last RMaint should elect "Needs documenting", always. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #19 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- I think the 'Needs documenting' tag serves as a list of all bugs that need an eye cast to make the decision as to whether to document or not.. your right, the majority of bugfixes will likely be a simple switch to 'Resolved Fixed' and thus very quick to remove from the queue (I've already done that to a couple in fact). But there are some bugfixes with minor changes that affect functionality that I feel are worth updating documentation for.. so it's not a hard and fast rule. -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #21 from Martin Renvoize <martin.renvoize@ptfs-europe.com> --- Jonathan has highlighted that this may create a bit of bugzilla spam as part of the process.. if every bug goes through this new state those of us that are cc on a metric tonne of bugs will get an email for the change to 'Resolved fixed' I like that we're encouraging 'someone' to look at every bug and assess whether it needs a docs change or not.. but perhaps we could 'burden' the rmaints to be a little picky and do some of the obvious filterings at 'Not backporting' time.. when it's obviously a behind-the-scenes change that doesn't affect workflow, UX or UI they could just skip straight to Resolved Fixed still instead of using the middle 'Needs documenting' ? -- You are receiving this mail because: You are watching all bug changes.

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=30998 --- Comment #23 from David Nind <david@davidnind.com> --- Comments on comment #15 (Arthur) and comment #16 (Victor). I think Martin has tried to encourage that type of work flow - where a bug isn't pushed until the docs are done, but that hasn't worked that well for Koha. I'd more than welcome, and certainly encourage, contributions from developers for their bugs, but I realise that this may not necessarily be a strength or something they are interested in doing. Everyone can contribute to the docs, but there is a bit of a learning curve (although developers are at least familiar with git, so that is once less hurdle!). I'll take a look at updating our instructions and guidance, which I'm trying to cover in a "Content Development Guide". Slightly off-topic, but I'd probably like developers to focus on adding release notes before they tackle the documentation, for example: - This new feature [does XYZ]. - This enhancement [adds X and Y to Z]. - This fixes [XYZ] so that it does [expected behaviour], [instead of whatever error or problem was happening]. That way, it makes it much easier to identify if documentation updates are required (instead of having to read through the bug history/latest patches). -- You are receiving this mail because: You are watching all bug changes.