Open tukusejssirs opened 1 year ago
@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.
@MRIIOT, this is issue is currently in Backlog
project status. I am hesitant to move it into in progress
without your approval.
@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
@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? :wink: 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
proposed
in the project for this use case;debt
: improve the implementation/architecture:
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:
upstream
: an issue used to track an issue in an upstream component:
engineering
: issues related to our engineering system or our processes:
infrastructure
;infrastructure
to engineering
if we wanted to.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.
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.
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: https://github.com/Ladder99/ladder99/issues/13.
use-case and enhancement are interchangeable to me and discussions to support.
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 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. :wink:
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:
use case
label;enhancement
for (requests of) both new features and old feature improvements;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. :man_shrugging:
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.
:+1:
@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
:
agent
;cache
;console
;random
;agent
;autoclave/cpc
;egress/console
;egress/shdr
;erp/jobbos
;modbus
;mqtt
;opc
;plc4x
;printer/zebra
;scale/dymo
.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. :wink:
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. :thinking:
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.
@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 toenhancement
label.
Sure.
We might want to add
application:cli
label which could be used when a particular issue is related to anyl99
shell command (e.g.l99 start
);
Sounds good - added.
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
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:
bug
:#d73a4a
;docs/
);enhancement
:#a2eeef
;dependencies
:#4b4b4c
;l99
; it should not be assigned when a new feature is added that requires a dependency to be added or updated;application:$appName
:#5b0e6f
;appName
:adapter
;compiler
;meter
;recorder
;relay
;simulator
;library:$libName
:#e99695
;libName
;infrastructure
:#86504a
;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);documentation
:#0075ca
;docs/
; it should not be assigned when a new feature is added (in that case the docs modification should be done implicitly);tests
:#1b263d
;localization
:#f11add
;component:$componentName
:#c5def5
;componentName
;duplicate
:#cfd3d7
;good first issue
:#7057ff
;wontfix
:help wanted
:#008672
;invalid
:#e4e669
;Label assignment rules:
application:$appName
andlibrary:$libName
should be mutually exclusive labels. Whenever a particular issue is related to particular app/library, use of such label is required.application:$appName
andlibrary:$libName
labels.TODO and questions:
application:$appName
andlibrary:$libName
, do we need some other scoped labels? For example,component:$name
where$name
could be a driver type foradapter
. It could be a module name (in Nest/Angular terminology; e.g. a monitoring feature). (Currently, possiblename
s of thecomponent:$name
areadapter
,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 thecomponent:$name
labels.bug
label is added,enhancement
label removed), however, that is not in the scope of this issue (at least right now).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 intolibs/
folder) or not.use case
andquestion
labels;enhancement
?