Project Management | Open Library Docs
Skip to content Project Management Using Github We drive most of our work on the Open Library project off GitHub Issues in the InternetArchive/OpenLibrary GitHub repo . Milestones Much of our work is done by volunteers. So we plan very lightly, by year and by quarter, given the resources we have available. As new volunteers join, plans may change to accommodate their skills and interests. Things we'd like to get done during a given year get the milestone for that year, e.g.
"2019". For things we expect to be done in by the end of a given quarter, we apply the quarterly milestone, e.g. "2019 Q1" for things to get done on or before March 31, 2019. Milestones are closed when their deadline arrives. Issues associated with that milestone that are not done get rescheduled (the milestone is changed) or backlogged (labeled State: Backlogged ). Assignee The assignee of an issue is the person responsible for its completion.
An example of a common search might be assignee:cdrini label:"state: work in progress" to see what Drini is working on. Singular ownership is important to make sure things don't fall on the floor. We therefore avoid multiple assignees. Most issues have multiple individuals involved in various aspects of assessing and resolving it - those people are "mentioned" (e.g. "@hornc") in the issue comments. If multiple folks are working together to solve a problem, use @mentions in the issue comments, or if it is really complicated, create a subissue to be owned by another person.
Don't forget to mention the parent issue in the first comment. Any open bug that is unowned is in need of triage. Labeling Issues We reserve a set of labels for use with Github issues, to assist with issue handling and project management for OpenLibrary. Most generally, an issue evolves through a series of states, for example: submitted -> assessed -> scheduled -> fixed -> closed. On the way down that path, lots of things can happen.
The labels below can be applied and removed during initial triage (either by the submitter, or by an initial triage), and thereafter by the owner of the bug. The sections below contain: Assignee Milestones Managed Labels By Group Type Priority State Needs Close Theme Affects Module Additional Labels Finding Issues by Label Note the following: The label's label (!) matters. Each label starts with a prefix that groups the labels into sorted list.
Labels prefixed with "~" are deprecated. Labels prefixed with a developer's initials are managed by that developer (for their own purposes). Label color matters. Each prefix has a common hue (developers, pick your hue!). Generally, the prefixes are orthogonal (an issue can only have one Priority , only one Type , from the managed set). So if you see an issue with more than one label of a given hue, something might be awry.
Labels get reduced color saturation (greyed out) labels to indicate they are deprecated. Lower color values (whiter) typically suggest reduced urgency. The label text also has these indicators, for accessibility (since not everyone sees all the colors). Be careful touching labels on issues belonging to others! People are using the labels to actively manage their activity. You can add and remove labels from an issue: a.
At the time you submit the issue, as the submitter. b. The assignee/owner of an issue can label it as they see fit, using their own labels, and using managed labels according to the guidelines. c. The Bug Triage Owner will adjust issues during triage. d. Deputies will review and adjust labels as needed for issues in their area. e. If you're not sure, ask the issue owner, the Bug Triage Owner, @brad2014, or @mek. (The comment stream of the issue, or the slack channel are great places to raise these questions).
Triage Every issue on Open Library's tracker should be assigned a Lead: @person and a Priority: # label by a member of staff. Issues which have Needs: Lead and or Needs: Triage labels do not yet have a lead/mentor assigned and have not yet been vetted or evaluated for the community. Once an issue has been triaged, members of the community may request to be assigned to an issue and enjoy the mentorship of the designated Lead .
Priority Priority describes how urgent the bug is. Very urgent bugs generally have an active conversation on the slack channel, so that they can be fixed right away. Color Label Description Priority 0: Immediate Issues that prevent users from using the site, or that corrupt site data. [managed] Priority 1: Urgent Do this week, receiving emails, time sensitive. [managed] Priority 2: High Important, as time permits. [managed] Priority 3: Normal Issues that we can consider at our leisure. [managed] Priority 4: Low An issue, but should be worked on when no other pressing work can be done. [managed] When a priority label is applied to an issue by the submitter, or on any issue without an owner, it represents a suggestion, not a decision.
Priorities are not immutable - even while an issue is being worked on, the owner may decide to move the priority up or down. Although priorities indicate urgency rather than timing, a helpful frame for assigning priority is to ask questions such as these - think of them as "rules of thumb": Is the issue preventing numerous users from successfully using the website? Is the issue related to leaking sensitive information?
Is the issue related to usage or running processes actively corrupting our data? Does it really need to be fixed in the next 48 hours? Mark it Priority 0: Urgent . If it requires conversation or multiple developers to fix, they should all be talking in a slack channel right now. Should a developer interrupt and set aside their current activity to get this issue resolved? Does it need to be fixed in the next 14 days? Assign an owner who will label it Priority 1: High .
If you can't find a volunteer to own it, it can't be Priority 1 . The other priority labels are available to memorialize your assessment. They mostly indicate, "I've looked at this, and it is not urgent." At most, one Priority label can be assigned to an issue. If there is no Priority label, consider the priority unassessed. It is good form to mark all your issues with some priority level, because it gives us a historical record of the distribution of issues by priority.
Leads Every issue on Open Library must be assigned a lead label. A Lead is member of the community with domain expertise who has been appointed by staff to help manage a specific aspect of Open Library (such as search, design, javascript, i18n, etc). Anyone may apply to be considered for a specific lead position. The Lead is responsible for: Project Management: Defining and breaking down an issue to making sure it's actionable and labeled Mentoring: Monitoring the issue for new comments and helpfully responding to questions and comments Assignment: Assigning members of the community (or themselves) to an issue and committing to give them mentorship Escalation: Raising relevant questions, issues, or concerns about designs and requirements to members of staff Review: Overseeing the code review process for PRs addressing the issue See the Team Leads Labels to get an idea of who to tag.
Managed Labels By Group Labels are grouped by prefix and color. If you create a label outside the managed set, prefix it with your initials and give your personal labels a common color. We are continually evolving the managed set to meet our needs. If you think a label deserves to be in the managed set, just mention it. The labels are grouped into different axes for slicing and dicing issues: Type What kind of issue this is.
Is it something that is broken that should (perhaps) be fixed, or is it a request for a new feature or enhancement, or is it a reminder to reorganize or clean up some aspect of the code base? Color Label Description Type: Bug Something isn't as intended. [managed] Type: Feature Issue describes new functionality we'd like to imple
The rest of this page is on the live site.