Proposal: Labels for Issues on GitHub TYPO3-Documentation

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)

help-wanted

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)
  • “developer certification v9”

Other:

  • “decision required”

  • “doing” - someone is already working on this

  • 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:

We can use the app GitHub app Settings:

  1. Must be installed once for TYPO3-Documentation
  2. A file .github/settings.yml can be created. All settings are optional. We overwrite the labels
  3. 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.

See my sample test repo:

Resources

2 Likes

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. :smile:

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! :+1:

1 Like

@pixeldesu Generally agree. Some comments:

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.

Hope this clarifies this a bit.

Understood. I will not translate documentation to other languages then english :slight_smile: Just thought, that it

for PR which requires to be translated to english.