Updates in GitHub Labels


#1

We are going to update the labels in the repository. We’ve have identified a couple of use-cases that are ambiguous and it will also bring some improvement to how related issues can be bundled. This will help working on them together, prepare releases changelog easier and simplifying how the repository can be navigated.

These are the changes to be applied:

  • Rename kind:wrong-semantic to topic:compiler:semantic. For changes related to how the compiler is working with respect the design of the language. Wrong types inferred for example.

  • Add topic:lang. For changes/issues related to the semantic of the language. How the language should work. Usually will imply changing the compiler/parser. Mostly used for additions of the language or fixing ambiguos constructs.

  • Add topic:lang:macros. For changes/issues related to how the macro subsystem should work. Not related to macros of the stdlib.

  • Rename topic:concurrency to topic:stdlib:concurrency.

  • Rename topic:debugger to topic:compiler:debugger. For changes/issues related to debugging information and exception handling

  • Rename topic:docs to kind:docs. For changes about adding or fixing docs in some module indicated by topic.

  • Add topic:tools:docs. For changes/issues related to the docs generation tool.

  • Rename topic:formatter to topic:tools:formatter. For changes/issues related to the formatter tool.

  • Rename topic:generics to topic:compiler:generics. For changes/issues related to how generics are implmented in the compiler. This is needed becuase the implementation is not complete and are some issues that might be worth handling the together.

  • Rename topic:macros to topic:stdlib:macros. For changes to the macros provided by the stdlib.

  • Rename topic:parser to topic:compiler:parser.

  • Rename topic:performance to performance. So it’s clear that a change of a specific topic: is not a bug/feature but a performance change, probably also flagged as kind:refactor.

  • Rename topic:playground to topic:tools:playground.

  • Rename topic:security to topic:stdlib:crypto.

  • Rename topic:specs to topic:stdlib:spec. For changes/issues related to the spec framework.

  • Add kind:specs. For improvements of the specs of a module without adding features.

  • Add topic:stdlib:runtime. For changes related to internals/primitives of the language.

  • Add topic:stdlib:numeric, topic:stdlib:text, topic:stdlib:collection, topic:stdlib:serialization, topic:stdlib:time, topic:stdlib:files, topic:stdlib:networking, topic:stdlib:system, topic:stdlib:spec to narrow better the topic of a change and match the current changelog structrure.

  • Rename topic:type-system to topic:lang:type-system. For changes/issues related to the definition of type system of the language.

  • Rename topic:windows to platform:windows. For changes/issues related to windows support of a module (indicated by topic:).

  • Add platform. For changes/issues related to platform-specific support of a module (indicated by topic:).

The complete list of labels will end up being the following:

  • Kind
    • kind:bug
    • kind:docs
    • kind:feature
    • kind:question
    • kind:refactor
    • kind:specs
  • Topic
    • topic:lang
    • topic:lang:macros
    • topic:lang:type-system
    • topic:stdlib
    • topic:stdlib:collection
    • topic:stdlib:concurrency
    • topic:stdlib:crypto
    • topic:stdlib:files
    • topic:stdlib:macros
    • topic:stdlib:networking
    • topic:stdlib:numeric
    • topic:stdlib:runtime
    • topic:stdlib:serialization
    • topic:stdlib:spec
    • topic:stdlib:spec
    • topic:stdlib:system
    • topic:stdlib:text
    • topic:stdlib:time
    • topic:compiler
    • topic:compiler:debugger
    • topic:compiler:generics
    • topic:compiler:parser
    • topic:compiler:semantic
    • topic:tools
    • topic:tools:docs
    • topic:tools:formatter
    • topic:tools:playground
    • topic:infrastructure
  • Extra labels
    • breaking-change
    • performance
  • Platform specific
    • platform
    • platform:windows
  • PR labels
    • pr:needs-review
    • pr:wip
  • Community labels
    • community:in-progress
    • community:newcomer
    • community:shard-idea
    • community:to-design
    • community:to-document
    • community:to-implement
    • community:to-research
  • Statys labels
    • status:accepted
    • status:deferred
    • status:discussion
    • status:draft
    • status:duplicate
    • status:implemented
    • status:invalid
    • status:needs-more-info
    • status:someday
    • status:wontfix

This should help to assign every change an accurate kind: and topic:.


#2

A note: kind:wrong-semantic means the compiler compiles a file but it behaves differently from what you would expect (regarding the language’s docs and your expectations). That means for example doing 2 + 2 and getting 5 as a result. These are bugs that should be prioritized because they are silent bugs: your program works, but wrong, and it doesn’t crash.

Renaming it to topic:compiler:semantic would hide this fact (it looks like this label just means “review the semantic of a given feature”).

Please don’t do that :slight_smile:

(or, well, maybe choose a name that’s a bit more drastic :-P)


#3

Do we want to make a distinction between compiler-performance (for example improving some generated code) vs stdlib-performance (some optimization in some method)?


#4

Besides my minor comments above, I really like the changes :tada:


#5

Performance changes in the stdlib would be: performance + topic:stdlib:collection.
Performance changes in the compiler code would be: performance + topic:compiler
Performance changes in the emitted code could be: performance + topic:stdlib:runtime


#6

I understand that they are more severe. But the motivation was to tag more accurately the nature of the change.

If we want to prioritize issues with some criteria that should not depend on the name of the label but on which labels we want to focus.

I’m happy to build something to give visibility on the overall current status of the issues to tag them and prioritize them.


#7

Sounds great!

Just one remark regarding renaming topic:security to topic:stdlib:crypto. Security is far more than cryptography. For example, https://github.com/crystal-lang/crystal/pull/5259 is currently tagged topic:security because it is about closing a XSS vulnerability.
I’d suggest to add some kind of label for security issues, maybe just plain vulnerability or security?


#8

Btw. are there any plans to improve assigning labels? Not even a quarter of all issues opened in the last 30 days has been tagged with any labels.
Merged PRs are usually properly labeled, but for open PRs the quote is again less than a quarter.

Having a good taxonomy is great, but it doesn’t help much when it’s usage is limited.


#9

I agree security is more than crypto, but most of the issues were about crypto AFAIK.
We can keep a security as Extra label, like performance, to give some visibility there.


#10

I definitely agree. Unfortunately I don’t know of a solution to allow non-collaborators to allow just labelling.
We do tag PRs since they are the source information for the changelog.

Sometimes issues are left behind until someone try to address it. If that someone is from the community then he/she is unable to tag, a PR might come and then nobody cares about tagging. But if the story doesn’t come to an end a tag would help a bit for definitely.

This topic also helps to have a defined shared criteria. Until the next change.


#11

This topic also helps to have a defined shared criteria. Until the next change .

For better visibility, the current list should perhaps be put in the Github wiki.


#12

FYI Labels have been updated in GitHub.

Thanks for the input :bowing_man:

Maybe CONTRIBUTING.md could be updated to reflect the intent of each label or that could be left in the description of each label. I’m not sure were it will be more visible.


#13

I suppose the label colors on Github don’t have a semantic meaning?

topic:compiler:semantic is hard to read with black text on a dark red background.


#14

You are right. Also, I would try to keep red just for bugs.


#15

Changed :-)

It’s a random process involving between 1 and 5 clicks of the suggest-color by github.

Red is used in: breacking-chages, kind:bug, security.


#16

I’ve just sneaked in a pr:needs-work label. I hope that’s fine with everybody. I encountered a couple of PRs waiting for updates by their author for quite some time and it makes sense to tag them for this status.


#17

Apropos GitHub labels, I’ve been really wanting to help out with Crystal for quite some time now, but frankly, I’m scared to do so, I like building something from the ground and up.

What I wish is more community:newcomer labels… ATM just 3 out of 676 issues are tagged so, and I image quite a lot of those issues could be tagged with it.


#18

Yeah, tagging more such issues is on my TODO list. Although it’s probably not a really huge number of newcomer-friendly issues. Those tend to be resolved rather quickly (tagged or not) and only the more complex ones stick around. About every second issue targets the compiler, which is definitely not newcomer-friendly.