Difficulty Ratings for Issues/PRs

[FoamyGuy]

There was a little bit of discussion around this topic in the weeds during weekly meeting on 2/28. The issue here is meant as a central place to discuss and collect ideas about the concept.

The core of this idea is to attempt assign "difficulty ratings" to issues and PRs within the circuitpython ecosystem. Good First Issue is essentially the same concept this, but we're proposing to have a few other statuses that indicate different / higher difficulty levels.

The primary goal being to give folks some rough idea of how difficulty it might be to complete a given task. I think it would make it more likely that folks can find issues and PRs that are at or just above their current experience level to give them confidence to attempt to tackle them and potentially make it easier for them to know when it's time to "level up" and start looking into more difficult tasks.

Originally discussed as a scale of 0-10 with 0 being the least difficulty, likely things like correcting a typo within a doc string or comment and similar tasks that have the least amount of complexity or difficulty. In my mind anything marked Good First Issue would likely be a 0 on the difficulty scale.

At the opposite end 10 would be the most complex / difficult types of tasks. Like introducing a brand new port for a device that doesn't currently support CircuitPython. Or implementing some new relatively complex feature within the core that doesn't exist today.

Thinking it over a bit I think it may be good to use a smaller scale and maybe non-numeric to try to convey that it is not an exact science. Everyone has a different experience level which means difficulty of a task could be different for different folks. The goal would be to aim for giving someone without a lot of prior experience some guess about how hard a task might be to accomplish.

To that end I think something like the following ratings may be better than the 0-10 number:

• Good First Issue - Exists already and is the lowest level of difficulty. A good example of this is fixing a typo within a comment or doc string.
• Low Difficulty - More complexity than 'good first issue' but still not too. Probably involves making relatively minor edits to code or typing information.
• Medium Difficulty - Another step up, this on likely involves more substantial code edits. Maybe refactoring a class or function fixing a small bug, or implementing a new relatively non-complex feature
• High difficulty - Highest difficulty rating. Likely requires a good amount of experience. Introducing a brand new port to circuitpython or implementing a complex feature within the core

It's worth noting that we do not need to be exact in these ratings, they are somewhat subjective and that is okay. It's meant for someone to be able to quickly assign a rough estimate to a task that gives other folks the chance to understand whether it's within their capabilities to attempt to tackle it. I wouldn't need to be adhered to 100% perfectly across the board.

If this is something that we want to eventually start doing, one detail that we'll need to nail down is what is the best way technologically to implement it. good first issue already exists as a label within github perhaps creating a few more difficulty level labels would be sufficient, or maybe there is some other mechanism that would be better for one reason or another.

[tannewt]

My feeling is that difficulty ratings will be too vague. I think categories could be more informative and less arbitrary.

Instead, I think we could do a better job labeling issues (aka categorizing) and explaining which are easier than others. For example, "crash" is tough if you don't use a debugger. "documentation" may be easier. "circuitpython api" may be easier because the API structure is regular. The port labels make it easier to find an issue for boards that you already have.

[gamblor21]

A couple thoughts from what I recall when I was starting out not too long ago. I found that a lot of "Good First Issues" were almost too simple. Maybe not bad to direct someone to do one to get used to the CI and how PRs work but if you have some C experience they really are a "first issue only".

I'm not sure of the value but I could see having wanted to look at levels like:

• Add a feature to an existing module / fix bugs in something existing
• Add a new module to a single port or shared module code
• Add core features / new port type requests

My personal path went from some tiny issue to working to add adafruit_bus_device to the core and onwards.

Thinking about it as I ramble, better labeling helps for sure but I think also a tag like "looking for help" that can let newer members know this is an issue where no one is working on it and would be useful work for the project. As an example I know there is a lot of want for more advanced audio features, so that could be marked as "looking for help" as much as say adding another parameter to countio (made up example).