meta: review our issue title prefixes and labels

[jorgeorpinel]

UPDATE: Jump to #895 (comment) for summarized results of this discussion.

---

Title prefixes

By this I mean what we start issue/PR titles with e.g. "meta: " in this one.

We don't really have even a suggested list. We just follow a similar pattern as in the core repo, which I think is based on the core Commit message format guidelines.

My suggestion is to leave it flexible but recommend the following ones:

• For documentation text changes use:
  • the doc section name e.g. "get-started: " or "cmd-ref: ".
  • feature-based prefixes for changes spanning several sections e.g. "config: " or "lock: " (typically dvc command names).
  • other docs/wide labels like "nav:" or "term: " (for terminology stuff).
• For source code changes are expected, try to specify one of the 3 parts of the code base:
  • "server: " node server code e.g. changes to server.js, sidebar.js files
  • "app: " server-side web app code (Next.js) – except React/JSX
  • "ui: " most React/JSX, and other front-end stuff
• Use "docs: " for general stuff or when unsure?

Labels

I feel like our current labels are a strange mix of "pears and apples" e.g. docs is kind of used for everything, and engine used kind of loosely for changes probably involving the pages/ and src/ dirs. We I just look at the available ones and assign them ad hoc.

Here are my suggestions:

• Keep these default type labels: bug, enhancement, question (actually, not sure we really want questions here since we have a chat and a forum.)
• Use doc/content for actual documentation contents (text in .md files)
• Keep optional priority based labels p1, p2, p3.
• Use docs-engine for the code related to our special /doc... page
  And maybe these special docs engine component nested labels: docs-engine/nav (sidebar stuff) and docs-engine/glossary (tooltips).
• Keep optional flag labels: duplicate, invalid, wontfix (known issues) – recommended for tickets closed without having been addressed.
• Leave automatic labels like dependencies and weekly-digest, of course.

[jorgeorpinel]

I realize it may not be that important to create such a system now, especially for this repo, but as the team grows it may become more important to adopt something like this, especially in the core repo, so doing it here first as an experiment could be useful.

[shcheklein]

let's discuss this next 1-1 :) certain things could be (and should be improved), but I think you underestimate the logic behind the current system (doc label, label vs title prefix, etc, etc - all these things have some logic behind them ... again not saying we should keep them this way and/or they could not be improved).

[jorgeorpinel]

Per private conversation I think we agree that

• we want to use labels for most general categories (doc-website, doc-engine, doc-content, and maybe blog in the future) as well as the other stuff mentioned above (issue type, priority, etc.)

and that

• the prefixes will try to indicate the component within the general categories, for example:

  • For doc-website: pages i.e. "home: ", "features: ", "community: ", etc.
  • For doc-engine: by feature e.g. "md: " (Markdown rendering), "nav: " (sidebar), "glossary: " (& tooltips), "link: ", etc.
  • For doc-content: sections i.e. "get-started: ", "cmd ref: ", etc. or per-feature/command e.g. "repro: ", "remote add: ", "cache: "

  But we can keep these flexible, no need to define a full list of possible prefixes right now. They will probably improve with time.

Please close if you agree @shcheklein and I'll update the labels accordingly. We can then try doing this, and keep the closed issue as a future reference.

[shcheklein]

sounds good!

[jorgeorpinel]

Another idea here: Should we move this into the repo Wiki? Or maybe even create a wiki label for this and other similar meta-issues?

[shcheklein]

@jorgeorpinel yep, wiki sounds good!

[jorgeorpinel]

OK, copied to https://github.com/iterative/dvc.org/wiki/Issue-labels-and-prefixes.

[jorgeorpinel]

We can then try doing this

OK to begin this, I renamed website->doc-website, engine-> doc-engine, and docs->doc-content and made sure the first page + of doc-content is properly labeled and prefixed. Will continue with this progressively but I'm not planning to review all 200+ issues, just quickly the necessary ones 🙂