Define issue label list

[tukusejssirs]

We already have som issue labels (mostly GitHub default) defined, however, we could do better.

Also we could improve our usage of labels. @bburns currently uses the first part of issue titles, which is not the best practice. We should remove the ‘labels’ from issue titles and try to create such issue titles that could be eventually used as commit messages (i.e. they should be short and descriptive), however, that is a separate issue.

Just a sidenote: on GitHub, I miss scoped labels that I love on GitLab (which I prefer over GitHub).

We should use labels to define:

• [required: exactly one] a top-level issue category labels:
  • bug:
    • colour: #d73a4a;
    • description: Something isn’t working;
    • rules: whenever an issue is a report of a bug anywhere in the code (apps, libs, scripts) or bug (incorrect explanation or other major mistake) in the app documentation (in docs/);
  • enhancement:
    • colour: #a2eeef;
    • description: New feature or enhancement of existing feature;
    • rules: whenever an issue is a dealing with a new feature or enhancement of an existing feature, including feature requests; also improvements to the documentation should be labelled with this label;
  • dependencies:
    • colour: #4b4b4c;
    • description: Pull requests that update a dependency file;
    • rules: whenever we update the dependencies of l99; it should not be assigned when a new feature is added that requires a dependency to be added or updated;
• [required unless library label is used or issue is not related to any particular app] application name:
  • application:$appName:
    • colour: #5b0e6f;
    • description: Anything related to a specific application;
    • rules: whenever the issue is related to a specific application which name is part of the label after colon;
    • current possible values of appName:
      • adapter;
      • compiler;
      • meter;
      • recorder;
      • relay;
      • simulator;
• [required unless application label is used or issue is not related to any particular library] library name:
  • library:$libName:
    • colour: #e99695;
    • description: Anything related to a specific library;
    • rules: whenever the issue is related to a specific library which name is part of the label after colon;
    • currently, there is no possible value of libName;
• [required unless issue is not related to infractructure/tooling] infrastructure:
  • infrastructure:
    • colour: #86504a;
    • description: Anything related to the surrounding tools and infrastructure;
    • rules: whenever we update, improve or add some tools (e.g. Docker, Nx, Nest, ESLint, Prettier, etc) used by l99 not directly related to the code (apps/libs) itself; it should not be assigned when a new feature is added (in that case the tests addition should be done implicitly);
• [optional: at most one] ‘additional’ labels:
  • documentation:
    • colour: #0075ca;
    • description: Improvements or additions to documentation;
    • rules: whenever an issue is modifies the documentation in docs/; it should not be assigned when a new feature is added (in that case the docs modification should be done implicitly);
  • tests:
    • colour: #1b263d;
    • description: Test improvements or additions;
    • rules: whenever we update, improve or add some tests; it should not be assigned when a new feature is added (in that case the tests addition should be done implicitly);
  • localization:
    • colour: #f11add;
    • description: Anything related to localization, internationalization and locales;
    • rules: whenever we update, improve or add some stuff regarding l10n, i18n and locales; it should not be assigned when a new feature is added (in that case the localization addition/changes should be done implicitly if they are required);
• [optional] optionally use other labels are remarks (‘optional’ labels):
  • component:$componentName:
    • colour: #c5def5;
    • description: Anything related to a specific component;
    • rules: whenever the issue is related to a specific component which name is part of the label after colon;
    • TODO: current possible values of componentName;
  • duplicate:
    • colour: #cfd3d7;
    • description: This issue or pull request already exists;
    • rules: whenever an issue deals with the same or similar stuff as another issue;
  • good first issue:
    • colour: #7057ff;
    • description: Good for newcomers;
  • wontfix:
    • This will not be worked on
  • help wanted:
    • colour: #008672;
    • description: Extra attention is needed;
  • invalid:
    • colour: #e4e669;
    • description: This doesn't seem right;

---

Label assignment rules:

1. Question issues should be converted to GitHub Discussions (there is button for that in the issues). Same should be true when a discussion is not a discussion—we should convert it to an issue.
2. Each issue should have exactly one top-level issue category level.
3. application:$appName and library:$libName should be mutually exclusive labels. Whenever a particular issue is related to particular app/library, use of such label is required.
4. We can use at most one ‘additional’ label.
5. Whenever we add/remove/rename an app/library, we should reflect this in the application:$appName and library:$libName labels.

---

TODO and questions:

• Are label colours, descriptions and rules okay with you all?
• Besides application:$appName and library:$libName, do we need some other scoped labels? For example, component:$name where $name could be a driver type for adapter. It could be a module name (in Nest/Angular terminology; e.g. a monitoring feature). (Currently, possible names of the component:$name are adapter, agent, relay, shdr.) However, the question is whether we need such in-depth labelling for issues. IMHO it is too much for now, therefore I suggest to remove the component:$name labels.
• We could use GitHub Actions to force some rules (like when bug label is added, enhancement label removed), however, that is not in the scope of this issue (at least right now).
• As for libraries, I haven’t added a label for them, as currently, the libraries (e.g. drivers in adapter) are part of the app (microservices). Currently, I am not sure if those libraries (or plugins, as @bburns calls them) should be considered as separate parts, or if they should be later moved out of the app into separate library (like into libs/ folder) or not.
• I removed use case and question labels;
• Should we create separate labels for new features and enhancements of existing features instead of enhancement?

[tukusejssirs]

@Ladder99/development, I am mostly done creating a list of labels I find useful to use in this repository (potentially in all repos under Ladder99 org, with some minor modifications), I haven’t updated the actual label list though.

All proposed labels have colours, description and rules when to use defined. There are stuff to consider/evaluate (see the TODO and questions in the description).

I can create the labels (ideally under org level, with some labels specifically related to l99 under repo level), however, I’d rather do that after some kind of confirmation, probably after answering the questions.

[tukusejssirs]

@MRIIOT, this is issue is currently in Backlog project status. I am hesitant to move it into in progress without your approval.

[bburns]

@bburns currently uses the first part of issue titles, which is not the best practice.

I use categories/labels as the first part of a title so they can be sorted into groups, and it's easy to see at a glance what category an issue belongs to in plain text. The table view fits better on my laptop also. But labels have color, and can have >1, so labels win 🤷

Are label colours, descriptions and rules okay with you all?

Yes, though I still prefer 'service' and 'driver' over 'application' and 'library'. I think users would get confused over the latter 2, which are more generic.

Besides application:$appName and library:$libName, do we need some other scoped labels? For example, component:$name where $name could be a driver type for adapter. It could be a module name (in Nest/Angular terminology; e.g. a monitoring feature). (Currently, possible names of the component:$name are adapter, agent, relay, shdr.) However, the question is whether we need such in-depth labelling for issues. IMHO it is too much for now, therefore I suggest to remove the component:$name labels.

Yes, let's rename the component:* labels to service:* and driver:shdr. If other scoped labels come up, we can add them.

We could use GitHub Actions to force some rules (like when bug label is added, enhancement label removed), however, that is not in the scope of this issue (at least right now).

Hmm, interesting

As for libraries, I haven’t added a label for them, as currently, the libraries (e.g. drivers in adapter) are part of the app (microservices). Currently, I am not sure if those libraries (or plugins, as @bburns calls them) should be considered as separate parts, or if they should be later moved out of the app into separate library (like into libs/ folder) or not.

Yeah, we can see when move to things to Nx.

We might want to remove use case label;

I'd keep it - we could create as many labels as makes sense to categorize issues - eg vscode is very well managed and has 400+ labels - https://github.com/microsoft/vscode/labels.

Should we create separate labels for new features and enhancements of existing features instead of enhancement?

idk - vscode seems to just have 'feature-request' - https://github.com/microsoft/vscode/wiki/Issue-Grooming#categorizing-issues

[tukusejssirs]

@bburns currently uses the first part of issue titles, which is not the best practice.

I use categories/labels as the first part of a title so they can be sorted into groups, and it's easy to see at a glance what category an issue belongs to in plain text. The table view fits better on my laptop also. But labels have color, and can have >1, so labels win 🤷

I understand your approach, however, filtering based on categories/labels in the title is not possible, because all you can do then, is to search for strings that might also be used in the issue description and comments, thus you cannot find what you actually need. On the other hand, filtering based on issue labels is 100 % functional (unless an issue has incorrect label assigned).

Are label colours, descriptions and rules okay with you all?

Yes, though I still prefer 'service' and 'driver' over 'application' and 'library'. I think users would get confused over the latter 2, which are more generic.

I disagree that it’ll be confusing to the users.

Are you talking about end-users? They don’t care how we call the apps. They won’t (presumably) actually work on the code, all they would at most do is to follow the docs and run some commands.

Are you talking about users who will set l99 up for a customer? They will mostly only follow the docs and run the commands.

Are you talking about contributing users/devs? They will understand it whatever we call them, whether they are apps, services, microservices, libraries, plugins …

I actually don’t really care (as long as we understand each other), however, I still suggest to use apps/ and libs/ folders, esp after we move to Nx monorepo workspace.

Besides application:$appName and library:$libName, do we need some other scoped labels? For example, component:$name where $name could be a driver type for adapter. It could be a module name (in Nest/Angular terminology; e.g. a monitoring feature). (Currently, possible names of the component:$name are adapter, agent, relay, shdr.) However, the question is whether we need such in-depth labelling for issues. IMHO it is too much for now, therefore I suggest to remove the component:$name labels.

Yes, let's rename the component:* labels to service:* and driver:shdr.

So, are you suggesting to keep the component:$name/driver:$name labels? Do we actually need that much information/details on issues?

If other scoped labels come up, we can add them.

This I meant implicitly. I added this explicitly to the rules.

We might want to remove use case label;

I'd keep it - we could create as many labels as makes sense to categorize issues - eg vscode is very well managed and has 400+ labels - https://github.com/microsoft/vscode/labels.

What would be the use case for use case labels?

Are they to be used as customer feature requests? Then I suggest to use enhancement label.

Are they to be used as questions about implementation/usage/whatever? Then I suggest to use GitHub Discussions for that use case. Example (closed) issue from that past that should be asked in the discussions: #13.

Any other use case of use case label you had in mind? Do you still disagree with me? 😉 What are your arguments?

we could create as many labels as makes sense to categorize issues

Yes and no. The more labels we have, the harder it’ll be to maintain both label list and their assignment to issues. We are a small team, we need to code more than work on issues.

Of course, the more we automate the labels, the more labels we potentially could have. That said, however, I am against useless labels. By a useless label I mean labels that have no real value to us.

vscode is very well managed and has 400+ labels - https://github.com/microsoft/vscode/labels.

Yes, but they the manpower and they set up the label automation, we have neither.

Should we create separate labels for new features and enhancements of existing features instead of enhancement?

idk - vscode seems to just have 'feature-request'

I actually don’t care about the label names. I used enhancement because it is/was the name of the default GitHub label. We can rename all of them.

On the other, semantically, I prefer not using request in the label names, as from my point of requesting a feature and suggesting a feature and working on a feature is all the same from code point of view. However, there is a difference between a new feature and improvement/enhancement of an existing feature and is what I am asking in the description.

https://github.com/microsoft/vscode/wiki/Issue-Grooming#categorizing-issues

I am open to introduce some other labels, however, I’d prefer to keep the list as slim as possible and all the labels need to have defined rules when a particular label should be used. Also, all labels need to have some value to us.

Some comments on the VSCode type labels:

• under-discussion: not decided whether the issue is a bug or feature
  • currently, we don’t need this one, as we use proposed in the project for this use case;
• debt: improve the implementation/architecture:
  • it more or less overlaps with infrastructure (when the technical debt is on the tooling side) and enhancement (when the technical debt is the code side);
• needs more info: not possible to assign a type label due to missing information:
  • we might add this one;
• upstream: an issue used to track an issue in an upstream component:
  • we might add this one;
• engineering: issues related to our engineering system or our processes:
  • this is more or less the same use case as our infrastructure;
  • we could rename infrastructure to engineering if we wanted to.

[MRIIOT]

application:$appName:
description: Anything related to a specific application;
rules: whenever the issue is related to a specific application which name is part of the label after colon;
library:$libName:
description: Anything related to a specific library;
rules: whenever the issue is related to a specific library which name is part of the label after colon;

---

Yes, though I still prefer 'service' and 'driver' over 'application' and 'library'. I think users would get confused over the latter 2, which are more generic.

Besides application:$appName and library:$libName, do we need some other scoped labels? For example, component:$name where $name could be a driver type for adapter. It could be a module name (in Nest/Angular terminology; e.g. a monitoring feature). (Currently, possible names of the component:$name are adapter, agent, relay, shdr.) However, the question is whether we need such in-depth labelling for issues. IMHO it is too much for now, therefore I suggest to remove the component:$name labels.

Yes, let's rename the component:* labels to service:* and driver:shdr. If other scoped labels come up, we can add them.

---

@tukusejssirs
When you are talking about application, you mean : adapter, meter, relay ?
When you are talking about library, you mean external libraries ?

@bburns
Sounds like service and application are interchangeable? If we rename the folder from services to apps then application makes sense.
If library is an external library, then application:adapter component:modbus does make some sense to point the issue at something specific within adapter. But I can see that the component tags will just continue growing and be a dump all.

[MRIIOT]

I use categories/labels as the first part of a title so they can be sorted into groups, and it's easy to see at a glance what category an issue belongs to in plain text. The table view fits better on my laptop also. But labels have color, and can have >1, so labels win 🤷

This is the job for labels for sure, not issue title.

[MRIIOT]

What would be the use case for use case labels?

Are they to be used as customer feature requests? Then I suggest to use enhancement label.

Are they to be used as questions about implementation/usage/whatever? Then I suggest to use GitHub Discussions for that use case. Example (closed) issue from that past that should be asked in the discussions: #13.

use-case and enhancement are interchangeable to me and discussions to support.

[MRIIOT]

we could create as many labels as makes sense to categorize issues

Yes and no. The more labels we have, the harder it’ll be to maintain both label list and their assignment to issues. We are a small team, we need to code more than work on issues.

One thing where @bburns and I differ is that he is a bottom up kind of guy, and I'm a top down kind of guy (https://en.wikipedia.org/wiki/Top-down_and_bottom-up_design). We meet somewhere in the middle after discussing specifications. How might we get better at these approaches? In my opinion, we have painted l99 to the best of our ability without knowing what paint to use. Now we have a chance to step back and look at the picture, pick it apart, and really make design effort into what is to come next.

Everything else in the conversation looks good to me.

[tukusejssirs]

@tukusejssirs
When you are talking about application, you mean : adapter, meter, relay ?
When you are talking about library, you mean external libraries ?

When I talk about application, I mean any app that could run on its own, like gateway, (micro-) service, CLI app, …, therefore in l99, all apps are in services/ folder.

Regarding libraries, a library is a piece of code that cannot be run on its own, it can be imported (or used in general) by other apps/libs. A library is a separate package though. Currently, in l99 repo there are no libraries yet, although @bburns uses common/ folders albeit on app-level only. Some stuff from common/ folders could be made a libary and some stuff could be shared among multiple apps in a shared library (i.e. a library imported by multiple apps).

@bburns
Sounds like service and application are interchangeable? If we rename the folder from services to apps then application makes sense.

Yeah, all services are apps, however, not all apps (in general) are (micro-) services. 😉

If library is an external library, then application:adapter component:modbus does make some sense to point the issue at something specific within adapter.

A library can be an external dependency, however, in that case its code is in node_modules/ folder. Libararies that would be in libs/ folder would be libraries used by l99 apps only.

We can keep component:$type if you wish.

But I can see that the component tags will just continue growing and be a dump all.

Also the list of apps and libs might grow; then we need to update the labels accordingly.

use-case and enhancement are interchangeable to me and discussions to support.

@MRIIOT, as I understand it, you agree with my suggestion, that is:

• remove use case label;
• use enhancement for (requests of) both new features and old feature improvements;
• use GitHub discussions for questions/support.

Did I understand you right?

One thing where @bburns and I differ is that he is a bottom up kind of guy, and I'm a top down kind of guy (https://en.wikipedia.org/wiki/Top-down_and_bottom-up_design).

I have never heard about top-down/bottom-up approaches; I consider myself an analytist, thus I might be a top-down guy, however, I use both approaches whichever I feel the best to be used at a particular moment. 🤷‍♂️

We meet somewhere in the middle after discussing specifications. How might we get better at these approaches? In my opinion, we have painted l99 to the best of our ability without knowing what paint to use. Now we have a chance to step back and look at the picture, pick it apart, and really make design effort into what is to come next.

Well, I have to add to this. I’ll create labels as I suggested in the issue description, assign labels to the issues (I’ll do my best) and we’ll see.

Everything else in the conversation looks good to me.

👍

[tukusejssirs]

@bburns, what do you consider a component? Here is a list of devices and drivers from adapter app which might be considered a component. The list definitely needs to be modified.

• adapter:
  • devices:
    • agent;
    • cache;
    • console;
    • random;
  • drivers:
    • agent;
    • autoclave/cpc;
    • egress/console;
    • egress/shdr;
    • erp/jobbos;
    • modbus;
    • mqtt;
    • opc;
    • plc4x;
    • printer/zebra;
    • scale/dymo.

[tukusejssirs]

I have created all the labels listed in the issue description. I have removed use case and question labels.

Note that I didn’t bother much with decision of what colour should be assigned to which label; I tried to set different colours for different labels though. If someone wants to update the, feel free to choose any colour you want. 😉

I did my best to assign labels to all issues and thus to and thus to catogorise them. If someone disagrees with my choice, it should be discussed in that particular issue. Some issues might be on the edge of the labelling rules though. 🤔

I removed ‘labels’ from the issue titles. I also updated the titles in order to be more descriptive, use sentence case and imperative mode.

@MRIIOT, we could add this to the public docs, although it is not a hard requirement, just a nice to have.

Until I get a word from @bburns, I won’t add nor update component:$componentName labels.

I also didn’t set application:$appName labels everywhere; @bburns might be better suited to assign these labels.

We could consider adding design label for architecture/design proposals. This label could be used in addition to enhancement label.

We might want to add application:cli label which could be used when a particular issue is related to any l99 shell command (e.g. l99 start); optionally we could also add the individual shell commands (e.g. start, build) as components (e.g. component:start). For now, I used infrastructure for anything related to those l99 shell commands, albeit it is not nice choice.

[bburns]

@MRIIOT, we could add this to the public docs, although it is not a hard requirement, just a nice to have.

Yeah a summary would be good for us and contributors - could add to docs.

Until I get a word from @bburns, I won’t add nor update component:$componentName labels.

Converted these to application: and removed component: labels.

And renamed component:shdr to driver:shdr - would be nice to have labels for all the drivers, but adding new labels in this thing is a pain. Unless you could just tag things like #driver:foo - but you can't.

I also didn’t set application:$appName labels everywhere; @bburns might be better suited to assign these labels.

Okay, added some more where relevant.

We could consider adding design label for architecture/design proposals. This label could be used in addition to enhancement label.

Sure.

We might want to add application:cli label which could be used when a particular issue is related to any l99 shell command (e.g. l99 start);

Sounds good - added.

[bburns]

The current list, obtained by copy/pasting table - no export ability.

application:adapter
application:agent
application:cli
application:compiler
application:meter
application:recorder
application:relay
application:simulator
bug
dependencies
documentation
driver:shdr
duplicate
enhancement
good first issue
help wanted
infrastructure
invalid
localization
tests
wontfix