Renovate: docs: create a tagging guide

[HonkingGoose]

What would you like Renovate to be able to do?

Document how to tag issues.
I recently got triage rights, and so can label issues.
I don't know about the back-end structure of Renovate, and so some labels are not very clear for me.
This makes me hesitant to tag away on the repository.
It also leads to questions fired at the maintainers whenever things are unclear.

We can prevent this with a proper "tagging guide".

Did you already have any implementation ideas?

Create a new file called how_to_tag_issues.md or something like that and put it in the directory that we use for other development type docs.

This file will describe what different categories of tags there are, and how they should be used.
Maybe we can also add a bit of background behind each category of tags, so that it's easier to learn how to use them.

Once we have figured out how to use each tag, we can also improve the descriptions that are in the GitHub label section.

Are there any workarounds or alternative ideas you've tried to avoid needing this feature?

Learn how to tag by trial and error, and ask the maintainer to help each time I'm not sure.

Is this a feature you'd be interested in implementing yourself?

Yes, I will need help from the maintainers with explaining each tag category, as I'm not familiar with the Renovate back-end code. :smile:

[HonkingGoose]

Hi @rarkins :wave:

I've made an inventory of all tags, and put them in categories as best I could. Can you check the categories?

Tag categories

Severity tags

breaking
major

Priority tags

pri0-blocker
pri1-critical
pri2-important
pri3-normal
pri4-low
wontfix

Type of issue tags

bug
docs
duplicate
feature
refactor

Housekeeping tags

good first issue
help wanted
needs reproduction
reproduced

Miscellaneous tags

gitfs
hacktoberfest
hacktoberfest-accepted
internal
ready
self hosted

Datasource tags

datasource:docker
datasource:git-submodule
datasource:git-tags
datasource:jenkins
datasource:maven
datasource:nuget
datasource:packagist
datasource:pypi
datasource:rubygems
datasource:terraform-module
datasource:terraform-provider

Manager tags

manager:bazel
manager:buildkite
manager:bundler
manager:cargo
manager:circleci
manager:cocoapods
manager:composer
manager:docker-compose
manager:dockerfile
manager:github-actions
manager:gitlab-ci
manager:gomod
manager:gradle
manager:helm
manager:helm-values
manager:kubernetes
manager:kustomize
manager:maven
manager:meteor
manager:mix
manager:npm
manager:nuget
manager:pip_requirements
manager:pip_setup
manager:pipenv
manager:poetry
manager:ruby-version
manager:sbt
manager:swift
manager:terraform
manager:travis

New stuff tags

new datasource
new package manager
new platform
new versioning

Platform tags

platform:azure
platform:bitbucket
platform:gitea
platform:github
platform:gitlab

Worker tags

worker:branch
worker:global
worker:onboarding
worker:pr

Semantic release bot tags

released
semantic-release

Discussion on what we should cover per category

I think it's helpful to at least explain each category of tags, and give a bit of background information, and to add links to the (development) docs that explains that category in more detail.

Questions about the tags:

These are the questions that popped into my head while I was doing the tag categorization.

• When to use the Severity tags?
• How to choose a priority?
• How to select the proper type of issue tag?
• When to apply a help wanted or good first issue tag?
• What is the internal tag about?
• How to decide if something needs reproduction?
• What are the datasource: tags about? How can I see in the issue what datasource is affected?
• What are the manager: tags about? How can I see in the issue what manager is used?
• When to apply the new .... tags?
• How to select the proper platform: tag?
• What are worker: tags about? How can I see in the issue what worker is used?

We should also improve the description of tags

Many tags do not have a description on how to use them to best effect.
I think once we have the tagging guide finished, we should add the descriptions to the tags.
This way the description can act as a short reminder of the things we covered in the tagging guide.

[rarkins]

@HonkingGoose I think most of these should be added to a markdown file in docs/development/. Could you create a Draft PR with a skeleton outline plus any descriptions you think are probably correct, and then the rest of us can make suggestions to the PR until it's ready to merge?

[HonkingGoose]

@rarkins I have opened a lot of docs related issues, and I'm ready to start working on all of them. However @viceice is still busy with work to migrate to Docusaurus v2.

Do you want me to wait with creating PRs until we're using Docusaurus v2 on the master branch? Or do you want me to open PRs anyways, and deal with migrating those later?

[rarkins]

@viceice a new doc like this shouldn't cause any major issues, right? We don't even have develop docs on the existing site yet anyway

[viceice]

Yes, it's okay to change the docs, as I've no changes targeting existing docs folders for now. I think I need some more time until I can make more progress on docusaurus.

[JamieMagee]

I am a fan of how NixOS/nixpkgs uses labels. They use numbers to group labels together. Check out all their labels here: https://github.com/NixOS/nixpkgs/labels

For example, if we adopted a similar approach, we might have: 1.datasource: docker, 1.datasource: pypi, etc.

[HonkingGoose]

@JamieMagee That's very clean and nice indeed! I like it! :smile:

[rarkins]

@JamieMagee I don't see much benefit in that approach on first scan:

• grouping of labels within a category: using consistent naming prefixes and colors like we do today achieves this (e.g. manager:, and datasource:)
• ordering of categories: we don't have a need for ordering
• ensuring completeness: they have 11 numbers, and I wondered if every issue and PR needs all 11 (!) but that doesn't seem to be the case either

[renovate-release]

:tada: This issue has been resolved in version 23.78.0 :tada:

The release is available on:

• GitHub release
• 23.78.0

Your semantic-release bot :package::rocket: