Radish alpha
h
heartwood
rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5
Radicle Heartwood Protocol & Stack
Radicle
Git
Issues › 450fa78d
issue: Labels as Tags with Values
Open lorenz opened 1 year ago

I extracted all labels from my local COB cache:

sqlite3 ~/.radicle/cobs/cache.db \
    "select distinct json_extract(issue, '$.labels') from issues;" \
  | jq -rs 'flatten | sort | unique | .[]'

This prints a total of 92 labels, which I reproduce in a compact form for completeness:

Inbox
RPB:column:awaiting review
RPB:column:doing
RPB:column:done
RPB:priority:x   (many of these, where x is an integer)
UI Fix
UI fix
UX Refine
bug
c:beginner
chore
design
documentation
e:low
enhancement
feature
feature improvement
feature request
generic task
good first issue
in-review
onboarding
p:high
p:later
p:low
p:medium
p:next
p:now
radicle-explorer
sync
t:bug
t:feature
t:maintenance
test
ui
ux
v1.0

I notice patterns:

  1. Namespacing via :, e.g. RPB:… for “Radicle Planning Board”.
  2. “Values” after the last colon, e.g. p:high (priority is high), p:low (priority is low).
  3. There are duplicates resulting from variations in capitalization, e.g. UI Fix vs. UI fix.

I would like to propose:

  1. Keep namespacing by colon :.
  2. Instead of denoting values after the last colon, use the symbol = to separate between keys and values. Thus, I would prefer p=high over p:high, and RPB:column=doing over RPB:column:doing.
  3. When in doubt, use lowercase. Thus, I would prefer rpb:column=doing over RPB:column=doing.

In the following I use the terms “label” and “tag” interchangeably.

The reason for proposal (1.) is that I do see a value in a tag without a value. However, it becomes harder to distinguish a tag without value from a namespaced one if the separator for namespacing and the separator between key and value are identical.

My opinion is inspired by tags in OpenStreetMap. See https://wiki.openstreetmap.org/wiki/Tags and https://taginfo.openstreetmap.org/. Like with OSM, I would not want to impose a particular tagging scheme globally, but propose the above for the heartwood repository, ones closely related to Radicle itself, and when we implement tooling based on tags.

This issue should serve as a place for discussion of tagging schemes, in particular for the repositories maintained by the Radicle team.

rudolfs commented 1 year ago

I wonder if the namespacing and key=value pairs are even necessary? I think a new userland cob could be better suited for arranging these items on a timeline. But in general what you propose is better than what we have in the wild, so +1.

lorenz commented 1 year ago

I wonder if the namespacing and key=value pairs are even necessary?

Probably not strictly necessary, but I do understand the sentiment to encode “attributes” (e.g. priority) of an issue in an ordinal dimension (e.g. low, medium, high). Also, I do understand that the developers of the planning board decided to namespace the labels they would use. There are repositories on GitHub that have literally hundreds of labels, see e.g. https://github.com/NixOS/nixpkgs/labels, in this case you get lost without grouping/namespacing them somehow.

I think a new userland cob could be better suited for arranging these items on a timeline.

And that COB would contain the Issue ID, the lane it is in, and its position within that lane? Sure! I also thought about that. Thing is that tags are already there right now, and I wanted to share my opinion. Such a COB, while it sounds reasonable to have one, is still to be developed.

fintohaps commented 1 year ago

Thanks for starting the discussion! This sounds reasonable to me :) So, to follow on I’ll kick off what categories we should have.

We can take inspiration from the above and label all our heartwood labels as hw – it might be redundant in heartwood itself, but in the global cob cache, it’s at least distinct then. Happy to not use this prefix too.

Following that, we could have an optional crate specifier: cli, node, rh (remote-helper), cob, crypto, dag, fetch, etc.

I like the shorthand, p, for priority. I don’t mind if it’s numeric or ordinal.

I think we should be able to group them into some kind of milestone tag, or maybe even quarters (q1, q2, q3, q4)?

So as an example, we have a research issue for investigating revoked keys and their interaction with sigrefs, I want to label it so that it gets done this quarter with:

  • hw:p=high
  • hw:q2

Another example, Lorenz has an issue about improving the CLI output of rad sync, that doesn’t have to be done so soon:

  • hw:cli
  • hw:p=medium
  • hw:q2 He had too much work to do in this quarter so the label is changed:
  • hw:q3

What do you think? :)

lorenz commented 1 year ago

We can take inspiration from the above and label all our heartwood labels as hw – it might be redundant in heartwood itself, but in the global cob cache, it’s at least distinct then.

I actually think that the name of the repository itself is a bad example for a namespace, but it’s just my gut feeling.

Good examples or where it’s necessary IMO:

  • Automation (like the planning board)
  • External tools
  • Tags used across multiple repositories (but then the namespace would be this overarching thing, e.g. rad:…, not the repository)
  • For custom tags, e.g. only one person in the team wants to use “their” tags, e.g. lorenz:…, maybe even for their personal tooling.

I don’t think that distinction in the global COB cache is a good measure. It was just one way for me to obtain the list.

Happy to not use this prefix too.

I would like to avoid hw:…. We could think about rad:… or xyz.radicle:… for things we want cross-repo and for which we don’t want to start polluting the “global namespace”.

Following that, we could have an optional crate specifier: cli, node, rh (remote-helper), cob, crypto, dag, fetch, etc. […]

  • hw:cli

I would make that crate=cli, or if we want to be pedantic, rust:crate=cli, or very pedantic io.crates:crate=radicle-cli. I would also like to avoid abbreviations then, i.e. crate=radicle-remote-helper instead of crate=rh or even rh. One might be inclined to drop the prefix radicle- but then the question arises how to handle the radicle crate. Also note that we will hit issues that touch multiple crates. In this case I would like to propose to follow OSM again, and split values using ;, e.g. crate=radicle-cli;radicle-cob.

I think we should be able to group them into some kind of milestone tag, or maybe even quarters (q1, q2, q3, q4)?

Milestones sound good, I would not use them as keys, however, but as values, e.g. milestone=x.

I dislike to specify quarters without years, this creates overlaps every 12 months. As you know I am a proponent of ISO 8601, and would like to propose to use a format that is compatible with it. That might mean a date like 2025-06-31 or a week like 2025-W27. For quarters, we could use the non-standard notation 2025-Q2, 2025-Q3, 2025-Q4, 2026-Q1, … inspired by the notation of weeks in ISO 8601 which spans from 2025-W1 to 2025-W52. Again, I would also use this together with a key, like due=2025-Q3.

Another example, Lorenz has an issue about improving the CLI output of rad sync, that doesn’t have to be done so soon:

  • hw:cli
  • hw:p=medium
  • hw:q2

I’d counter that with

  • crate=radicle-cli
  • p=medium
  • due=2025-Q2
fintohaps commented 1 year ago

Great! I am not opinionated on the matter, and this works great for me :)

Sign in with GitHub to comment