We have already tagged some issues on GitHub with labels. This makes it easier for new contributors to find issues where they can easily contribute (e.g. via “good first issue”, see also How to Work With GitHub)
Issues labels also makes it easier for the team to do some basic project management. Along with using projects on GitHub and milestones.
What we already have and what is considered helpful
got feedback multiple times that “good first issue” is considered helpful (tip: login on GitHub first if you follow the link, or you will get 404 for this)
using the “developer certification v9” label makes it easier to prioritize and find issues for missing documentation needed for v9 developer certification
looking at the labels that the typo3.org team uses, we can get some other good ideas. For example, they tagged some issues depending on the skill that is required, e.g.:
Skill: Design
Skill: Backend
by default, GitHub uses the “help wanted” label to point out issues, e.g. in the overview of all repos. So it is probably good to use this for issues that are
described well (don’t need to much undocumented “insider” knowledge)
are important
actually need help (meaning someone is not already working on this and almost done)
Suggestion for issues:
We can use <category>: similar to typo3.org. This makes it easier to find a label in alphabetical list and gives the label more meaning. We can use lowercase only. Issues of same category get similar colors.
“good first issue” (easy issues, that can be finished in a small amount of time)
“help wanted” (for important issues that aren’t too complex and require little “inside” knowledge)
Skill labels describe required skill to fix issue:
“skill: typo3-dev” (TYPO3 developer)
“skill: typoscript”
“skill: fluid”
“skill: frontend”
“skill: english”
…
Complexity:
“complexity: beginner” (is the same as “good first issue”)
“complexity: difficult”
Content:
“content” (to differentiate pure content issues from usability, technical issues etc.)
“content: missing” (for people who want to write new content)
postponed (should be ignored for now - add comment describing why)
“priority: high” (high priority issues)
Implementation
Adding all the missing labels to all GitHub TYPO3-documentation repos is quite a job that involves tedious repetitive work. (As developers, we don’t like that). But, we have some tools that help:
A file .github/settings.yml can be created. All settings are optional. We overwrite the labels
We can use the same .github/settings.yml in all documentation repos (e.g. not in t3SphinxThemeRtd theme repo, but for example in “TYPO3 Explained” repo)
Advantage: we use the same file for all (documentation) repos, can be easily updated.
First of all, thank you for adopting my labelling concept, I introduced this to the typo3.org group on GitLab in the last sprint (the day before Developer Days started) to clean up the existing labels.
The whole idea of marking basically anything as skill-specific/skill-preferred is really nice as it will lower the barrier of approach, eventually making it easier for users to find issues they could work on.
I’m not so sure on “skill: english” though, because I presume you mean something along the lines of “proofreading/grammar/spellchecking” here. If it really is about translating something, e.g. someone submitted a German text because of lacking english skills, there should be an “Other” type of label called “translation required”.
“doing” is something I don’t think is required. If someone commits themselves to writing a piece of documentation (like leaving a comment in the relevant issue), they should get the issue assigned by a team member, so there’s an indicator on that. Created PRs should link back to an issue so a reference is visible and that should be enough information that something is currently worked on.
I like the approach of the settings.yml file to keep label definitions uniform between repositories, but all files need to be updated if the labelling gets changed in one or another place, that might get a bit chaotic in the long run if the workflow with the settings.yml isn’t properly documented for current and future contributors/team members.
All in all, I think the suggestions make sense and might help out structurally!
I’m not so sure on “skill: english” though, because I presume you mean something along the lines of “proofreading/grammar/spellchecking” here.
yes
If it really is about translating something, e.g. someone submitted a German text because of lacking english skills, there should be an “Other” type of label called “translation required”.
agreed.
Didn’t give much thought about how people could transmit a text for docs in another language. I was thinking along the lines of creating a Google doc and sending us a link. But adding a text in their native language as PR and then just getting it translated by someone may be even easier in the workflow: makes it more visible, anyone can participate. Thanks for this idea.
“translation required” might be a good one for a PR, but it would probably also make sense to specify the languages, e.g. “skill: german” and “skill: english” for translation from German → English.
btw. labels on GitHub can be used for issues + PR.
“doing” is something I don’t think is required.
The reason: we often assign issues to team members so at least one person feels responsible. This does not mean they would start working on this right away (because some of us have 20+ issues). It is usually appreciated if someone else grabs the issue and continues. But, I guess we could point that out with “help wanted” or in some other way. So, about this one: not sure.
all files need to be updated if the labelling gets changed in one or another place, that might get a bit chaotic in the long run if the workflow with the settings.yml isn’t properly documented
true. We should consider that. Still preferable to manually updating the labels, I think.
“translation required” might be a good one for a PR, but it would probably also make sense to specify the languages, e.g. “skill: german” and “skill: english” for translation from German → English.
Isn’t our target language english? Labels alike “translation required: french” would tell me, I could start translation if I’m familiar with french. But this would require an amount of predefined labels for most recent languages…
In general, our language (for the official docs) is English. However we have everything in place to easily render translations as well. So, theoretically, we can offer manuals in other languages. But currently, we rather discourage it. Problem is long term maintenance. Even keeping the English manual halfway up to date is quite a challenge. The Documentation Team cannot review or check manuals in other languages it is not fluid in.
There are several aspects to consider:
my original use of label “skill: english” which was just meant to mark issues or PR which required a good command of English language
Andreas brought in another use case: use the labels for translating. This further extends the idea that writing in English is a problem for some people. We lose good authors because they may be good writers but not for English. So the idea was to make PR possible in other languages and have other people translate. This idea is still very new. We have not worked out the details yet. I think this is a little beyond the scope of this decision (which is basically about defining labels for issues and PR)
Offering translated versions of manuals. This is an even bigger topic with long term problem of maintainability. Currently, I would not want to tackle this. I am afraid we will just have more unmaintained stuff. But I would not rule this out entirely. If a group of people more or less guarantees to maintain long term and has proven to follow through - we should reconsider.
Labels could be added first for translations from German, French, Italian, Nederlands and Russian. I would stick to the languages commonly used in the community. Possibly the “What’s New” slides could be used as guidance.
I would like to revisit this. Above, I categorized the labels by type. So we have “what skill is needed”, what type of task (e.g. documentation or developer, changelog issue etc.).
However, this task is starting to blow up and I think it would be a good idea, to start with the basics - the labels we really need. And give the rest a revisit later.
As for the color coding, doing “backport done” and “backport required” in same color (as same group of label) is not such a great idea, so I think this needs to be handled individually by what is most useful for target group. Here: people merging and backporting.
Essential labels: labels that are need and used currently
+1 for issue templates in general and add the labels automatically. That is often done in other projects to automatically label a new issues as “feature” or “bug” if entered via an issue template.
Though a little more difficult for docs.
We should probably define the general categories first, e.g. (draft!):
maintenance tasks (which would be similar to TASK in core)
Just thought, that it