search

exercism / docs

Exercism's docs. View them at Exercism's website, not on GitHub.
https://exercism.org/docs
44 stars 92 forks source link

standardize a core maintenance label taxonomy #27

Closed ghost closed 2 years ago

ghost commented 3 years ago

As a maintainer, I would like to leverage a shared vocabulary for managing a track. I believe we'll capture this somewhere but wanted to jot down this idea in case we don't.

one example

@exercism/rust has multiple generations of labels:

By unifying these labels under a common terminology we will improve the experience for maintainers, contributors, and word nerds like me.

I envision this as being a shared, core set of labels. Maintainers could introduce other labels as they see fit. But the shared terms should be preferred for the day-to-day operations of OSS maintenance.

SaschaMann commented 3 years ago

Julia uses these labels, which are based on the JS track but extended: https://github.com/exercism/julia/blob/main/.github/labels.yml

It uses an action to keep them in sync with the file.

iHiD commented 3 years ago

I'd really like to do this right. Primarily because I'd like to be able to do things with the labels across Exercism. For example, say "Want to check some grammar - check these issues". "Want to improve some stories - check these issues". And then let people filter by track etc. I think this could really open doors to early contributions.

[Insert general rant that people like doing different things and if we can make it really easy to contribute in the way that you want, rather than triaging first by the language to contribute to, I think we can get lots more contributions]

[Insert secondary rant about how we can have great templates/docs across exercise for how to do things, and labelling an issue can trigger an action that adds links to all those docs]

SleeplessByte commented 3 years ago

I'm pretty averse to changing what JavaScript (and TypeScript, and all the tooling) has been using for the past years, so the proposal needs to be incredibly solid for me to give it my support.

iHiD commented 3 years ago

@SleeplessByte Maybe the rest of us could benefit from adopting what JS has done 🙂 Do you have a document etc describing it?

SleeplessByte commented 3 years ago

Basically this: https://github.com/exercism/julia/blob/main/.github/labels.yml

I left invalid, help wanted and good first issue without emoji, because they are special in tooling. The reason I'm a bit change resistant is that we have links to the search with the issue label(s) including the emoji in the name in various documents 👯.

Here are the important ones:

Then a few to mark something as invalid:

I did for a hot minute think of doing type/x and status/y, but most of the time I needed these and just these. I purposefully don't have stale or need more information, or stuff like that.

Sascha added:

To re-iterate, the following have been unchanged because GitHub (and other tooling) expects them to be named exactly this:

iHiD commented 3 years ago

Great. That's a great list. Thanks.

So the ones I'd be keen to add would be things that are for specific types of checks. e.g.:

My thinking being that we can then create this "set" of issues for each new Exercise that gets merged, and in cases for existing exercises, and then crowd-source people who are specifically interested in those jobs. (This could happen via CI)

Another one/set might be to do with documentation for example.

SleeplessByte commented 3 years ago

Yeah, I could see sets for specific things like wip. That wouldn't be bad :)

SaschaMann commented 3 years ago

We could use the action and yml file to create a base set of labels that are synced across repos. Tracks could then add to the label file in their CI script. Technically they could also remove standard labels in the same way but that could be prevented by setting the right codeowners for the workflow.

BethanyG commented 3 years ago

I don't have time at the moment to list them all out, but Python is using a slightly different list that we'd like to keep. I don't think we deviate too far from JS or Julia (I cribbed most from of the tags from JS)...but I have added/altered some. I am also rather attached to my emoji and color choices. 😉 . Rather than use a tag for V3 🚀 , we're using an Issue title/project/milestone combo. Jury is still out on its effectiveness.

We added: claimed 🐾 in progress 🌿 new ___ ✨ (we added documentation and reference doc as categories) improve __ 💖 (one each for exercises, test cases, documentation, and reference documents).
draft

We also have/had these, which I added emoji to. maintainer action required❗ ❓ question❓ pinned 📌 awaiting review 👀 & please review 👀 good first issue 🐣 & beginner friendly 🐣 first-timers only 🐥 good first patch spam 🚫 on hold ✋🏽 enhancement 🦄 ✨ abandoned 🏚️

We make a distinction between chore🔧 (a maintenance task that crosses multiple exercises/docs/tests/etc.) vs maintainer chore 🔧 (a track-wide maintenance task that needs a maintainer to complete)

BethanyG commented 3 years ago

I like the WIP tags. Right now, I am folding tasks like those into "improvement issues" as a checkbox. See Python issue #2342, but separating and tagging is probably a better strategy.

SleeplessByte commented 3 years ago

(Sidenote. good first issue is a "special" tag that some things such as GitHub use to indicate issues to first-time contributors. Seems to not work when there is an emoji in there, which may or may not be okay).

iHiD commented 3 years ago

@BethanyG Thanks :) I'm excited about getting a really great superset of all these.

BethanyG commented 3 years ago

@SleeplessByte - yeah. 😸 Was going to note that I might need to cull (who needs both "needs review" and "please review"?) or edit out the emoji certain places -- especially if it breaks things like good first issue, which would defeat the whole purpose!

BethanyG commented 3 years ago

Went through and did some housekeeping. Here's the Python set: https://github.com/exercism/python/blob/main/.github/labels.yml

iHiD commented 3 years ago

As an update, we've largely done this with the x: labels, which are consumed by the website.

Do people feel there is value in adding further labels not used by the website, or should we consider this done?

BethanyG commented 3 years ago

I think there are people who won't interact with the website to look for issues/tasks. I also think there are tasks that for whichever reason might not end up listed on the website, but still need to be tracked or addressed. Not sure if those categories warrant exercism-wide labels, or if they're fine being labeled on a track-by-track basis.

Will there be explanations of the x tags and/or links in the exercism/exercism README, or another GitHub facing doc? That might help to direct contributors to run/click on the appropriate labels or filters to get lists that parallel the site.

iHiD commented 3 years ago

Will there be explanations of the x tags and/or links in the exercism/exercism README, or another GitHub facing doc? That might help to direct contributors to run/click on the appropriate labels or filters to get lists that parallel the site.

When the x: tags are added, a (bot) comment will be added to the issue explaining them, and then subsequently updated when the labels are updated. So someone looking at the issue shouldn't have to look anywhere else to know what to do (in terms of the high level categories). That said, I'd imagine most issues have descriptions detailed enough to superceed most of these comments anyway, so it's really an added layer of continuity from the website.

ErikSchierboom commented 3 years ago

@BethanyG We have this page: https://github.com/exercism/docs/blob/main/product/tasks.md