r0, 2020-01-04; author: @raulk
Table of contents
This document describes the issue/ticket labelling taxonomy that is being adopted in the libp2p project.
This taxonomy will be initially rolled out within the domains of go-libp2p, where it'll be trialled, adjusted and iterated upon. We hope it'll enhance navigability, searchability, discoverability and accessibility of issues, features, demands, requests, discussions, etc. on a path towards better organisation, structure, and, ultimately, accountability within, between and towards the community and implementation teams.
"Why is this important?", you may ask. A taxonomy is the basic building block that makes it possible to create workflows for triaging, discussing, development, and ultimately, delivery. In fact, issue classification is only the start of a set of methods and tools we desire to ship to help facilitate ecosystem alignment, foster collaboration, bolster transparency, streamline planning, and ultimately, reduce friction to keep the libp2p community engaged, vibrant, and excited about what's to come.
We are fans of iterative experimentation. In the next weeks/months, as we roll this out and adjust it, we will gather feedback and input from stakeholders across the ecosystem.
Our endgame is to converge on a system that pleases all language implementers, so that we can normalise this taxonomy across all language repos, and plan features and changes in total inter-alignment. We are convinced that by creating a cohesive and seamless experience across libp2p implementations, we'll unlock tremendous value for our beloved downstream users and developers.
These labels are an exception to the taxonomy below, but for a good reason: they are often searched by new contributors looking to get initially involved in a project, and are default across GitHub. (See GitHub help for details.)
- bounty
- help wanted
- good first issue
These labels describe some aspect of the issue itself. They can generally be set when the issue is first filed, or as discoveries are made. We will adopt tools that allow submitters to set these labels.
Defines the functional area of the libp2p stack an issue, report, question, etc. addresses. These labels refer to abstraction layers; to contextualise the issue to a specific implementation, also add a "component" label.
- area/conn-manager
- area/connection-bootstrapping
- area/nat-traversal
- area/peer-routing
- area/content-routing
- area/discovery
- area/identity
- area/multiplexing
- area/negotiation
- area/peerstore
- area/pubsub
- area/relay
- area/security-channel
- area/transport
- area/universal
Specifies the actual component (implementation) an issue refers to. Used when it's clear that an issue affects one or many specific components.
- comp/floodsub
- comp/gossipsub
- comp/kad-dht
- comp/noise
- comp/quic
- comp/secio
- comp/tcp
- comp/tls
- comp/webrtc
- comp/wss
- comp/yamux
Describes the nature of the issue.
- kind/bug
- kind/test
- kind/tracking-issue
- kind/question
- kind/enhancement
- kind/architecture
- kind/discussion
Subjectively estimates the difficulty of resolution of an issue, based on prior expertise about libp2p and its constructs, p2p networking, systems programming, etc.
Values and calibration guidance:
- dif/trivial: Can be confidently tackled by newcomers, who are widely unfamiliar with libp2p.
- dif/easy: A prexisting libp2p user should be able to pick this up.
- dif/medium: Prior experience in having developed libp2p modules is likely helpful.
- dif/hard: Suggests that having worked on the specific component affected by this issue is important.
- dif/expert: Requires extensive knowledge of the history, implications, ramifications of the issue, as well as deep understanding of the libp2p stack and experience with systems and network programming.
Estimates the amount of work. This axis is distinct to the complexity, e.g. something can be easy but require a lot of work, or vice versa.
Values and calibration guidance:
- effort/hours: one or multiple hours.
- effort/days: one or multiple days.
- effort/weeks: one or multiple weeks.
Contextualises the impact, and therefore the perceived/derived severity, of the issue.
- impact/regression
- impact/api-breakage
- impact/quality
- impact/dx
- impact/test-flakiness
Classifies issues pertaining to particular themes. Topics can be created to refer to epics, larger bodies of work, or ad-hoc endeavours.
- topic/interoperability
- topic/docs
- topic/infra
These labels describe some aspect of the execution on the issue. These labels are dynamic; they change as a result of planning, analysis, scoping, and generally applying the development workflow. They are usually set by maintainers.
Indicates the current implementation priority; used for planning and roadmapping purposes.
- P0: Critical.
- P1: High.
- P2: Medium.
- P3: Low.
Surfaces observations and facts about issues, facilitating progress to be made.
- need/contributor
- need/participation
- need/decision
- need/triage
- need/analysis
- need/author-input
- need/team-input
- need/community-input
- need/review
Marks the current status of the issue.
- status/done
- status/deferred
- status/in-progress
- status/blocked
- status/inactive
- status/ready
- status/rotten
- Create labels on go-libp2p declaratively.
- Write script to bulk transfer issues from inner repos to top-level go-libp2p
repo via the
transferIssueGraphQL mutation, attaching the appropriate area/component labels during the process. - Disable issue tracker in inner repos.
- Triage all issues to assign the remaining labels.
- Profit! We can finally start implementing workflows and using tools like ZenHub.