Github Issue Labels

[avidrucker]

These are the labels we use and some guidelines for their use. The goal of this post is to be a discussion for modifying labels and labeling processes. A more formalized version of our labeling system will be located in the handbook.

Priority (based on Flutter)

• P0 - "The world is on fire."
  • Should be = 0.
  • Data loss issue.
  • Athens is frozen on startup or on use — not being able to input is a kind of data loss.
• P1 - "A customer is on fire."
  • Should have less than 1 or 2
• P2 - "A customer is about to be on fire."
• P3
  • The highest priority level a bug can have that isn't affecting a top-tier customer or breaking the build.
  • Should be working on unless assignee is dealing with P0-P2 bug.
• P4
  • Default level for bugs. May not be fixed for a long time. Typically will migrate to P3 before we work on them unless part of Roadmap.
• P5
  • Default level for new feature requests. Valid but not important. Unlikely to work on such issues unless part of a long-term strategic plan.
• P6
  • Unlikely to ever be worked on. Use 👍 to promote to P5 or higher based on demand.

Type

• t/bug

Operating System

• os/mac
• os/linux
• os/windows

tasks

• Create Issue label descriptions Create Issue Label Descriptions #1208

questions

• should issue labeling be open to all with a disclaimer that some should be exclusively used by core team? or maybe a core team label to get their attention?

notes

• from @shanberg
  • sometimes it's nice for the palette to reflect the category of label, like all priority labels are reddish, domain labels are greenish, etc
  • or for the label color to reflect the severity/importance of the label, like P0 is strong red, P6 is weak red
• Conversation from Discord:

@avidrucker : How may I get the ability to assign labels to our GitHub issues? @Johnny @Jeff Tang 🏛
@tangjeff0 : what is your goal @avidrucker
avidrucker: Label new issues, as well as label issues I am working on directly or supporting
Primary goal: Increase interaction & contribution
Marking issues as needing attention, beginner friendly, increased documentation, etc.
Secondary goal: Hopefully to reduce the dependency on Discord as the driver for interaction

[tangjeff0]

Please create requests on this discussion, and not the issues themselves, e.g. here #997

We can batch the requests and actions, which will reduce the noise on the issues. Thank you for looking into this @avidrucker !

[avidrucker]

Proposed labels:

• ux: issues directly affecting the user experience that aren't necessarily features or bugs
• frontend: components, hiccup, CSS, etc.
• backend: databases, parsers, APIs, etc,
• brainstorm: for issues needing ideation
• feedback-needed: for issues that need a weigh-in or input from others
• discuss: for issues currently in discussion (not brainstorming or feedback) (note: rather than issues, use "discussions" to discuss, where the issue can link to the discussion)
• paused-issue: issues that are not closed, but are not being worked on currently
• pair-programming: issues marked to be done by two people simultaneously, recorded or not
• needs-testing
• f/test
• performance

[avidrucker]

So I'd advocate to leave in beginner-friendly or simple for clearly defined, well constrained issues. I'd advocate to remote the other "difficulty" tags (medium and hard) because they don't consistently add clear objective value for contributors.

Rough time estimate tags on the other hand will meet everyone's need for gaining further context on how much effort/time a task/issue will involve.

Plus: It also helps to see who added the label IMO - for e.g. when I or @shanberg mark a CSS issue with X time, we bring years of CSS experience to the "scoping" process, and if someone is not confident with CSS, they can apply their own "fudge" number/factor to get a rough picture of the time/complexity involved.

[shanberg]

I slightly favor complexity over difficulty, because complexity describes the work alone, and not the work divided by a theoretical average developer's skill level.

[tangjeff0]

I agree that difficulty is not good - will delete easy medium and hard.

I like complexity.

Time estimates only work for simple complexity things.

[avidrucker]

To increase constructive engagement with issues, I would like some issues to be broken down to the 30 min or smaller time estimate. This will help not only junior devs who have less experience with coding, Clojure, and open source in general, but it will also help more senior folks who want to mentor do so without hand holding.

[sid597]

how do we define complexity? I think the complexity of any issue depends on what time it is calculated, we freeze time look at its surroundings, factors, and then decide on the complexity and this assumes one has knowledge of their surroundings. In the case of Athens, people who are aware of the codebase and new changes being made to it are few (Jeff, Alex, Stuart). Keeping this in mind I have a few points :

• Deciding on the complexity of an issue can only be done by current core members, but this creates an issue of time commitment from their side.
• If we plan to carry on the bounties as a recruiting tool I think all the issues we label with complexity "X" should roughly be similar at all times which I think would not be possible.

I propose to let the contributor figure out the complexity of an issue and if needed discuss it, in case of using issues for hiring whenever the candidate picks up an issue they can then ask core members for analysis of the issue's complexity, this way upfront time commitment would not be needed and the problem of : all issues with complexity "x" should be similar, can be solved fairly.
What do you think @tangjeff0 @shanberg @avidrucker ?

[avidrucker]

Labeling To-Do's

• mark these with the ux label

  • Right sidebar width transition on resize feels "gooey" #1048
  • Increase visual signal of "hovered" state of arrows and bullets next to blocks #1016
  • Cursor is not placed at the location of the click in a block #566

• candidates for test verification:

  • Bloc search results and Athena results should be rendered #971
  • Improve athena research speed #969

• mark with labels discuss, architecture, backend, frontend, feedback-needed

  • rfct: store user state in a consistent way #997

• mark with label performance

  • Daily Pages scroll is slow #977

[tangjeff0]

These look all good to mark! @avidrucker

[avidrucker]

@shanberg Is the design label only for design tasks, or for anything design related?

• See issue: Windows install uses macOS-style icon #1041

[tangjeff0]

I think anything that is design-related. But what is the difference between ux and design?

[sid597]

More proposed labels, inspired by flutter's labels:

• customer/ : Can use this lable to mention if a customer raised the issue
  • Enterprise
  • user
  • open source sponsor
• depends-on/
  • person:
  • Other feature:
  • Plugin architecture: First need plugin architecture to implement this feature
  • Text editor: Cannot solve this bug or implement this feature without a new text editor
  • ..... All other features that are in the roadmap, so that we can see what current feature requests or bugs depending on the feature in roadmap
• found in release version/
  • ... mention last2/3 latest versions
• Need/
  • opinion
  • review
  • help
  • feedback
  • test
• Platform/
  • Computer/laptop
  • Mobile
• Status/ : Current status of an issue
  • assigned
  • open
  • PR raised
  • reviewing
  • brainstorming
  • self-assigned
• Issue/ : state of issue
  • fixed: can be a hack, not solution
  • solved
  • duplicate
  • timeout: author not responding
  • invalid
• tech-debt: An issue arose because of previously written code
• proposal
• easy-fix --> good first issue
• roadmap/ : feature in nth month/year of roadmap
  • ... values for n
• Not in the roadmap
• Remote: related to remote db
• Has reproducible steps
• Feature request by or agreed upon(can be via emoji or comment) by a core team member: This increases the priority of the request
• help popup: A help popup would be good for this issue
• User confused by behaviour: user is confused how to use some behaviour and if it is the right way to do this

[sid597]

• assigned for triage: Sometimes it's not clear what the appropriate labels are for an issue, or you suspect it may be a duplicate but you lack enough domain knowledge to know for sure. If you know someone who has the expertise to triage the issue, you can assign the issue to them and add the label assigned for triage, so the person knows that they are not expected to fix it, but to triage it.

[sid597]

• doc label: If the bug report is a question, then it probably belongs in Stack Overflow or on our #help channel or some other forum for getting help. However, if it appears that the reporter did try to read our documentation to find the answer, and failed, or, if you look in our documentation and find it is inadequate here, then please consider it a documentation bug (and update the summary accordingly).

[sid597]

If it seems to affect a lot of people but doesn't quite rise to the level of a release blocker, add the customer: crowd label (which means it affects many people) and then either the P1 label (if it's blocking people) or the P2 label (if it's not blocking people but is nonetheless serious). This will flag the bug for consideration during weekly triage (see the second section of this document).

[sid597]

Can also divide feature request label to :

• feature/
  • request
  • extend: Feature is already there and issue is asking to add more to it for example Render latex in links #859

[jsmorabito]

we might like to have a group of 'first good issue' labels that specify for whom the issue is good for (front-end, backend, design, etc)

[jsmorabito]

looks like by the way github leverages it we'll need to simply use the 'good first issue' label then further labels after that can help the potential contributor identify if its an issue within the domain theyre learning.