owned this note
owned this note
Published
Linked with GitHub
###### tags:`Team Admin`
# Issue labeling guidelines (proposal)
## Overall rules
- When triaging issues always label them in all categories.
When unsure, don't ignore the category, ask someone on the team for help.
## Label categories
### Effort
This is often hard to judge but it does not need to be very precise.
We consider tasks to require medium amount of effort by default and indicate low or
high effort when it's clear.
Single choice.
| Label | Description |
|-----------------|-------------|
| `epic effort` | Multi-stage task that may require coordination between team members across multiple PRs.
| `high effort` | A lot to implement but still doable by a single person. The task is large or difficult. Extra research may be required before it can be started.
| `medium effort` | Medium effort (the default).
| `low effort` | There is not much implementation work to be done. The task is very easy or tiny.
Decisions:
- We decided not to create a label for "medium effort" to avoid label overload.
It makes filtering a bit harder but still possible (you have to filter out other labels).
It also makes it less clear whether the issue has already been triaged or not but that
triaged issues will usually have other labels and untriaged ones are in a separate column
on the focus board.
- At a later meeting we decided to add a label for "medium effort" after all.
- @cameel: The `epic` label conflicts with the way this term is often used in project management so I'm renaming it to `epic effort` to distinguish it from the other `epic` label we started using after the Berlin on-site.
### Impact
Single choice.
| Label | Description |
|-----------------|-------------|
| `high impact` | Changes are very prominent and affect users or the project in a major way.
| `medium impact` | Medium impact (the default)
| `low impact` | Changes are not very noticeable or potential benefits are limited.
### Desirability
These labels express our opinion on how essential the task is to the project and,
to some extent, how mature the proposal is.
Anything that does not have enough merit to be at least `controversial` does not
need labeling and should be closed instead.
Single choice.
| Label | Description |
|------------------------|-------------|
| `selected-for-development` | Part of our short-term roadmap.
| `must have` | Something we consider an essential part of Solidity 1.0.
| `must have eventually` | Something we consider essential but not enough to prevent us from releasing Solidity 1.0 without it.
| `should have` | We like the idea but it's not important enough to be a part of the roadmap.
| `nice to have` | We don't see a good reason not to have it but won't go out of our way to implement it.
| *no label* | No decision yet but the issue is under consideration. It does have pros and cons and the discussion is still ongoing.
Decisions:
- `solidity 1.0` and `solidity 2.0` sound like too much of a commitment.
We'll use `must have` and `must have eventually` instead.
- We could have a `controversial` label for issues where we lean towards "no" but there are
people who have a different opinion and we don't want to shut down the discussion.
We decided instead to close such issues and direct people to discuss them on the forum.
- `selected-for-development` was originally called `roadmap` but this caused misunderstandings because not all important tasks we were working on were actually a part of the roadmap. This label is really just a level one step above `must have`.
### Project area
We have other labels for specific areas of the project but they do not cover everything.
We could add missing ones but for planning purposes I think that the following crude labels might be enough:
Single choice.
| Label | Description |
|-------------|-------------|
| `core` | Solidity or Yul language design, protocol design, core compiler components, formal verification
| `periphery` | Tools, tests, fuzzing, CI, build system, hosting of binaries, docs, style guide, translations
### Task type
Single choice.
| Label | Description |
|-----------------|-------------|
| *no label* | Feature or enhancement. A change visible to users. Usually has a changelog entry.
| `refactor` | Does not change anything observable by users or changes it in a very trivial way. Does not have a changelog entry. Typically something that improves code quality or is a preparation for other tasks,
| `bug` | A fix for something that's not working as designed. Always has a changelog entry.
| `documentation` | A text-only change in the documentation, READMEs, docstrings, comments or error messages.
| `research` | A research task meant to answer questions. Also any vague task that involves only gathering feedback for brainstorming. Does not involve any changes to the code.
| `testing` | Changes that involve only tests and/or testing tools.
Decisions:
- We don't need `feature` or `enhancement`.
They're too vague and in the extreme almost everything could be considered a feature.
The distinction between these two is also not very important for planning because
"impact" conveys most of that information.
### Blockers
Multiple choice.
| Label | Description |
|-----------------------------|-------------|
| `breaking change` | Cannot be included in a non-breaking release.
| `has external dependencies` | Can't be started or finished without something happening in other, independent projects first
| `has dependencies` | Depends on other issues or PRs that must be implemented or merged first.
| `unconfirmed` | We did not yet try or did not manage to confirm some of the claims in the description. Use e.g. when a bug is not obvious and has no example reproducing it, or when the problem a proposal is addressing does not appear to exist.
| `needs design` | The proposal is too vague to be implemented right away. Design must be fleshed out and some design decisions must be made.
### Benefits
Multiple choice.
| Label | Description |
|---------------|-------------|
| `performance` | Improves performance of the compiler or its infrastructure.
| `gas savings` | Improves performance of the produced bytecode in terms of gas usage.
Decisions:
- We could have a `security` label for issues that would improve security when solved.
Especially `security` + `bug` -> important bug.
However, we rarely have actual security issues and for important bugs the `codegen error`
label is usually enough.
- We could have a `usability` label for tasks that improve UX of the compiler or
add syntactic sugar for things already possible in the language.
In most cases it's not a very important piece information though and the criteria
are vague.
### Community impact
Multiple choice.
| Label | Description |
|----------------|-------------|
| `annoys users` | it's a huge pain point for the users and we have seen them complain about it.
Decisions:
- We could have a `community demand` label for issues that seem to be of high importance
to users, developers of apps and/or tools.
It would be based on the submitter, commentators and reactions in social media.
However, this has a big overlap with `annoys users` and in cases where it's different
enough, the `should have`/`nice to have` distinction is enough to convey the same information.
- We could have a `high friction` label for changes that are going to disrupt workflows
and/or may involve a lot of resistance from users.
For example when a change makes it considerably harder to support multiple versions.
However, `breaking change` already covers a lot of these cases.
### Other
These are still useful but don't fit well into any other category:
- `language design`
## Examples
| Issue | Proposed labels |
|----------------------------------------------------------------------------------------------------------------------------------|-----------------|
| [templates / generics #869](https://github.com/ethereum/solidity/issues/869) | `epic` `high impact` `must have` `core` `needs design`
| [Standard library brainstorming #10282](https://github.com/ethereum/solidity/issues/10282) | `high effort` `high impact` `must have` `core` `research`
| [Document the subtleties of the dispatcher #1289](https://github.com/ethereum/solidity/issues/1289) | `nice to have` `periphery` `documentation`
| [abi.encodeError(...) for custom errors #13339](https://github.com/ethereum/solidity/issues/13339) | `should have` `core`
| [Dynamic Libraries #2469](https://github.com/ethereum/solidity/issues/2469) | `high impact` `core` (should be closed)
| [Rename library to something more appropriate. #2699](https://github.com/ethereum/solidity/issues/2699) | `low impact` `low effort` `core` `breaking change`
| [Add source location tests #2987](https://github.com/ethereum/solidity/issues/2987) | `low impact` `should have` `periphery` `refactor`
| [Add support for compilation caching. #2779](https://github.com/ethereum/solidity/issues/2779) | `high effort` `should have` `core` `performance`
| [Support compile time in --via-ir #13050](https://github.com/ethereum/solidity/issues/13050) | `high effort` `must have eventually` `core` `performance`
| [Re-check if the identity precompile should be used for memcopy #12127](https://github.com/ethereum/solidity/issues/12127) | `low effort` `nice to have` `core` `gas savings`
| [Review if size_t not being 64-bit (on emscripten) can cause any issues #4025](https://github.com/ethereum/solidity/issues/4025) | `low impact` `nice to have` `core` `research`
| [Cleanup exceptions and exception handling. #3819](https://github.com/ethereum/solidity/issues/3819) | `low impact` `nice to have` `core` `refactor`
| [Better ASTVisitors #8315](https://github.com/ethereum/solidity/issues/8315) | `core` `refactor`
| [Documentation overhaul #3784](https://github.com/ethereum/solidity/issues/3784) | `epic` `should have` `documentation`
| [Explicit exporting of symbols #6482](https://github.com/ethereum/solidity/issues/6482) | `high impact` `core` `needs design`
| [Support for offchain keyword #12610](https://github.com/ethereum/solidity/issues/12610) | `core` (should be closed)
| [Turn on the optimizer by default #13223](https://github.com/ethereum/solidity/issues/13223) | `high impact` `low effort` `nice to have` `core` `breaking change`
#### Open questions
Open questions and their preliminary solutions that came up during actually labelling:
- At least in some cases, roadmap issues can be handled better by splitting into subissues. Should all of them be labelled roadmap or do we want to keep the roadmap label more manageable by reducing it to only a few issues? Current process: label all of them as roadmap and sort this out later.