Openlibrary: Update issue triage definition and Wiki

[xayhewalo]

Describe the solution you'd like

Redefine the repo's definition of triage to make the process more streamline and time-efficient.

Related: #2672

Philosophy

As Open Library grows, the amount of work that needs to be done is _much larger_
than the amount of time the developers have. There are two ways to combat this:

1. Increase the amount of developers
2. Streamline the workflow for completing issues and merging pull requests.

This issue and associated pull requests are designed to:

1. Decrease the barrier of entry for new collaborators to contribute to the project.
2. Minimize the amount of time developers spend handling issues and pull requests.
3. Wrangle issues that are irrelevant, solved, or contain useful information for current ongoing projects.

Proposal

• [ ] An issue is triaged when we can answer the following two questions:
  
  
  
  1. _Is this a legitimate issue_?
     
     
     
     
     
     • I.e: Is this actually a bug? Do we actually want to implement this feature?
     
     
     
  
  
  2. _How urgent is this issue_?
     
     
     
     
     
     • Is this issue related to an open Epic/milestone/project?
     
     
     
  
  
  3. Practical changes
     
     
     
     
     
     • We don't necessarily need to know how to resolve an issue for it to be triaged. The underlying problem of a bug or code needed to create a feature can be a mystery.
     
     
     
     • Triaged ~labels~ issues do not need an assignee. As long as the issue has a Type, State, and Priority it is considered triaged.
     
     
     
     • If an issue is legitimate but not considered urgent, a contributor can leave the labeled issue in the backlog without further investigation and still be compliant with this triaging process.
     
     
     
     • It is encouraged for contributors to provide relevant files or information that would make resolving the issue easier for new contributors to the project.
     
     
     
  
  

• [x] Rename Needs: Assessment to Needs: Triage and add the label Needs: Investigation to the set of available labels.

  • _Rationale_: Needs: Assessment has been used for marking an untriaged issue and marking an issue as needing more investigation.

• [x] Add a Type: Question label and corresponding issue template #2753

~- [ ] Add Needs: Triage~

• [ ] Add State: Backlogged to all issue templates EDIT: the usefulness of the State label is being contested besides Blocked

• [ ] Rephrase the issue template from "Describe the solution you'd like," it says something more along the lines of "Describe the problem that you'd like solved." per https://github.com/internetarchive/openlibrary/issues/2671#issuecomment-561401800 #2753

• [x] Rename css to Module: CSS and make it a managed label

• [x] Rename publicapis to Theme: Public APIs and make it a managed label

• [x] Rename Editing to Theme: Editing and make it a managed label

_Added from 2019-12-17 Community Call_

• [ ] Change Priority label formatting. I.e Priority 2: High to Priority: 2 assigned to @tfmorris

• [ ] Triaged labels need a Module?

• [ ] Triaged labels need a Theme?

Constraints

1. This process is dependent on a triager or triagers labeling incoming issues. It also requires contributors complying to the labeling Wiki.

2. Determining the "urgency" of a project is dependent on Open Library managing issues in milestones/project or some other type of public-facing road map.

3. It is still possible for issues "lost". I.e issues that were a work-in-progress, but were abandoned by the assignee for technical problems or other reasons. Example: #333 .

4. Some devs have requested a way to "score" issues so that it was easier to decide which were first on the todo list. The above changes don't provide a scoring system.

5. The proposed changes don't set expectations for triaged issues.. We many need to publicly state somewhere that large significant features can be triaged, but may not be implemented as the issue author requested.

Stakeholders

@brad2014 @mekarpeles

[BrittanyBunk]

@guyjeangilles Since this says 'needs community discussion', I'll add my input. I think all legitimate issues should be worked on. I don't think that should mean increasing the number of developers. Some issues likely don't involve developers. Here's a list of work that should be outsourced to the community ("crowdsourced"?):

• deciding the importance
• finding methods to solve it
• creating/using non-developer-required solutions
  So if an issue is found to be important and there's solutions to solve it, then developers come in. That decreases 3/4 of the work. Then the developers can focus on the developer part, not everything else.

I think we already do some of this. Another issue, as I've mentioned, is that adding a forum/PM features on OL would increase the ability of the community to solve issues - as the slack/github are not known/available to everyone.

Also, creating descriptions of roles and assigning them to people can also delegate more work to others - because it lets them know it's ok to work on it.

[xayhewalo]

@guyjeangilles Since this says 'needs community discussion', I'll add my input. I think all legitimate issues should be worked on.
I don't think that should mean increasing the number of developers. Some issues likely don't involve developers. Here's a list of work that should be outsourced to the community ("crowdsourced"?):

* deciding the importance

* finding methods to solve it

* creating/using non-developer-required solutions
  So if an issue is found to be important and there's solutions to solve it, then developers come in. That decreases 3/4 of the work. Then the developers can focus on the developer part, not everything else.

@BrittanyBunk Let me clarify my original statements. "Triage" is determining what is legitimate, not determining what should and shouldn't be worked on. Writing code is a serial process, that is, only one thing can be worked on at a time. So it's only natural to prioritize issues. That doesn't mean a legitimate issue shouldn't be worked it. It also doesn't necessarily mean issues labeled a lesser priority shouldn't be worked on by a developer.

You're proposed workflow for non-developers contributing is compliant with the process described in the original issue.

Also, creating descriptions of roles and assigning them to people can also delegate more work to others - because it lets them know it's ok to work on it.

This exists: https://github.com/internetarchive/openlibrary/wiki#meet-the-team
I would discourage from assigning people without their consent knowledge and this can generate disruptive amounts of notifications.

[BrittanyBunk]

I don't think we should limit assigning people roles just because of notifications. They don't have to receive notifications if they don't want to, but they would just be able to access what's available at their role level. Also, they'll be offered tasks that their role allows - and it's up to them to accept it. Notifications do help though for those that want it. It's just more privileges in the end.

What if people self-assign some of the lower ones and get offered higher privileges, in which they accept or not?

[BrittanyBunk]

See, I think you could have more people working on the website. I just think it might not be good, as then it'll overload the developers even more. However, doing this would lead to a lot of progress, and who knows? Maybe there might be a developer that shows up that can help. Overall, I think this may be something the website needs, as not everyone who volunteers will always be around, so this creates a steady flow automatically that's missing here.

To grow more people, here's what I would do:

• add https://github.com/internetarchive/openlibrary/wiki#meet-the-team (or at least the How we Communicate section) to the bottom of the page here:
  
• On that page, you could talk about the roles mentioned on this page: https://docs.google.com/document/d/1RUsUnIJM78gTr5ycewUJNwYHERBQdg_Tv-X-OZpwtRY/edit#heading=h.wqdfepesoone ("Readers, Loggers, Researchers, Librarians & Wiki Contributors, Moderators & Admin, developers" - along with their descriptions). I believe it's ok for people to self assign their roles up to Librarians & Wiki Contributors. The Moderators & Admin/developers should be assigned by voting and the admin).

I think that would increase the number of volunteers, but would kind of bottleneck at the higher levels, so there would need to be a part two of the plan to have the higher levels keep up with the demands.

[xayhewalo]

What if people self-assign some of the lower ones and get offered higher privileges, in which they accept or not?

This is exactly what I'd envision 👍

I hadn't thought about adding a volunteer section to the site page and allowing people to self-assign roles. I'm bring up these points on today's community call.

[tfmorris]

I think this looks good.

In addition to the proposed changes, I'd also like to see the Feature template slightly refocused so that instead of saying "Describe the solution you'd like," it says something more along the lines of "Describe the problem that you'd like solved." Then if someone needs a 2-wheeled vehicle that goes fast, we can offer them a motorcycle instead of building them a bicycle with really tall gears like they asked for.

[BrittanyBunk]

@guyjeangilles thank you for understanding and appreciating it. I think we have a great plan to move forward with. I think the customization of profiles would take the success of social media websites and apply it here to increase participation in improving the OL. Awesome.

[cdrini]

1. An issue is triaged when we can answer the following two questions...
   Triaged labels do not need an assignee.

• This point; so are you proposing that we should no longer try to enforce each issue having an assignee?

1. Rename Needs: Assessment to Needs: Triage and add the label Needs: Investigation to the set of available labels.
   
   
   
   • Seems good
   
   

1. Add a Type: Question/Discussion label and corresponding issue template
   
   
   
   • Seems good
   
   

1. Add Needs: Triage and State: Backlogged to all issue templates
   
   
   
   • Seems good
   
   

1. Rephrase the issue template from "Describe the solution you'd like," it says something more along the lines of "Describe the problem that you'd like solved." per https://github.com/internetarchive/openlibrary/issues/2671#issuecomment-561401800
   
   
   
   • I feel like that entire template could use an overhaul
   
   

1. Rename css to Module: CSS and make it a managed label
   
   
   
   • Seems good
   
   

1. Rename publicapis to Theme: PublicApis and make it a managed label
   
   
   
   • Let's use Theme: Public APIs instead; we have templates that use spaces in the kvp, so let's be consistent.
   
   

1. Rename Editing to Theme: Editing and make it a managed label
   
   
   
   • Seems good
   
   

Nicely done, @guyjeangilles ! This looks pretty great; I think all the label changes look terrific. I think Proposal 1 is the only one I have questions about; everything else looks great!

[xayhewalo]

1. An issue is triaged when we can answer the following two questions...
   Triaged labels do not need an assignee.

This point; so are you proposing that we should no longer try to enforce each issue having an assignee?

Sort of. If an issue is labeled Work in Progress, it's required to have an assignee. Otherwise, I propose an issue can be labeled Backlogged and left without an assignee.

1. Rephrase the issue template from "Describe the solution you'd like," it says something more along the lines of "Describe the problem that you'd like solved." per #2671 (comment)

I feel like that entire template could use an overhaul

Not a bad idea, but I think that should be a separate issue/PR though.

1. Rename publicapis to Theme: PublicApis and make it a managed label

Let's use Theme: Public APIs instead; we have templates that use spaces in the kvp, so let's be consistent.

Fair enough :+1:

[xayhewalo]

Updates for today's community call that will likely be it's own issue(s):

1. Change Priority label formatting. I.e Priority 2: High to Priority: 2 assigned to @tfmorris
2. Should triaged issues require Module and Theme?
3. Rotate triaging leads weekly/regularly?
4. Added requirements to project administration:
   
   
   
   1. Query-able topics. I.e label:"Module: Solr" label:"Priority 1: High" for high priority issues with no assignee
   
   
   2. Query for issues that have fallen through the cracks, i.e haven't been properly triaged or assessed
   
   
   3. Community knows who is the lead/mentor for an issue
   
   
   4. Admins can query for issues with no leads/mentors
   
   

[BrittanyBunk]

Yay, we finished this: https://github.com/internetarchive/openlibrary/issues/2671#issuecomment-560030797 here https://openlibrary.org/volunteer is a link at the bottom of the OL page and says 'volunteer'. Thanks @mekarpeles