From koha at hugh.run Mon Sep 14 05:32:42 2020 From: koha at hugh.run (Hugh Rundle) Date: Mon, 14 Sep 2020 13:32:42 +1000 Subject: [Koha-docs] a couple of questions about documentation workflows Message-ID: <5c8dc5d6-dc0c-437a-b43e-49c693286e0d@www.fastmail.com> Hi all After some time away I'm hoping to get involved with the Koha community again. I don't currently work at a Koha-using library, but I still think the project is great. I'm hoping someone can help me understand a couple of things about the documentation update workflow, because I'm a bit confused by the existing uh, documentation documentation. Specifically: 1. When providing updates to documentation aimed at old versions, should the pull request be aimed at a different git branch, or is everything simply merged to 'main' and someone else takes care of backporting documentation? 2. How are documentation updates tracked between Bugzilla, Taiga, and GitLab? Should I be referencing something in commit or PR messages, and if so, what should I be referencing? There seem to be many Taiga tickets that reference code bugs rather than documentation bugs, for example: should I reference the Bugzilla bug in this case, or the Taiga ticket, or both, or something else? thanks --- Hugh Rundle www.hughrundle.net GPG: 9184286B From david.nind at gmail.com Mon Sep 14 23:49:44 2020 From: david.nind at gmail.com (David Nind) Date: Tue, 15 Sep 2020 09:49:44 +1200 Subject: [Koha-docs] a couple of questions about documentation workflows In-Reply-To: <5c8dc5d6-dc0c-437a-b43e-49c693286e0d@www.fastmail.com> References: <5c8dc5d6-dc0c-437a-b43e-49c693286e0d@www.fastmail.com> Message-ID: Hi Hugh. Thanks for the questions! After some time away I'm hoping to get involved with the Koha community > again. I don't currently work at a Koha-using library, but I still think > the project is great. > I also don't work at or support a library using Koha - it is a great community and software. Your contributions would be most welcome, whether it is to the documentation or something else! > 1. When providing updates to documentation aimed at old versions, should > the pull request be aimed at a different git branch, or is everything > simply merged to 'main' and someone else takes care of backporting > documentation? > If the changes can be made to the main branch and can be cleanly merged without any changes for the older versions, then: - merge to the main branch - indicate that this change should also be made to older versions of the manual as well ==> basically, if there are no conflicts it is easy for the change to be "cherry picked" into older branches/versions of the manual If the change only applies to the older branch (for example, has been rewritten or is totally different in later versions), the merge request should be against that specific branch/version. If other changes have been made between the older branch and the main version that would cause a conflict, then separate merge requests with changes specific for each branch/version of the manual is required. 2. How are documentation updates tracked between Bugzilla, Taiga, and > GitLab? Should I be referencing something in commit or PR messages, and if > so, what should I be referencing? There seem to be many Taiga tickets that > reference code bugs rather than documentation bugs, for example: should I > reference the Bugzilla bug in this case, or the Taiga ticket, or both, or > something else? > There are Taiga tasks for each Bugzilla change - these come from the release notes. Caroline goes through and adds any changes from the release notes that require changes to the documentation. Here is the guide on how to ideally label commit messages: https://wiki.koha-community.org/wiki/Git_guide_for_documentation#Commit_messages Taiga [number] ([bugzilla number]): [Short title] Short paragraph(s) that succinctly describe the change and why the change was made. At the moment the GitLab issues are used for more management tasks for generating the documentation, rather than documentation bugs. Here is a useful starting point for the documentation team https://wiki.koha-community.org/wiki/Koha_Documentation_Team One thing I've been trying to do is bring everything together in a Content Development Guide for the Koha documentation. Ideally, this should make it easier to get up to speed contributing to the documentation and all the different aspects (covering the workflow, terminology, content strategy, and a style guide). David Nind | david.nind at gmail.com PO Box 12367, Thorndon, Wellington, New Zealand 6144 m. +64 21 0537 847 -------------- next part -------------- An HTML attachment was scrubbed... URL: From david.nind at gmail.com Tue Sep 15 00:12:39 2020 From: david.nind at gmail.com (David Nind) Date: Tue, 15 Sep 2020 10:12:39 +1200 Subject: [Koha-docs] a couple of questions about documentation workflows In-Reply-To: <5c8dc5d6-dc0c-437a-b43e-49c693286e0d@www.fastmail.com> References: <5c8dc5d6-dc0c-437a-b43e-49c693286e0d@www.fastmail.com> Message-ID: I've also added you as a member of the Taiga Koha Documentation project, so you can add, edit and assign documentation tasks to yourself. David Nind | david.nind at gmail.com PO Box 12367, Thorndon, Wellington, New Zealand 6144 m. +64 21 0537 847 -------------- next part -------------- An HTML attachment was scrubbed... URL: