Skip to content

HOW_WE_USE_GITHUB.md

Latest commit

 

History

History
357 lines (239 loc) · 22.7 KB

HOW_WE_USE_GITHUB.md

File metadata and controls

357 lines (239 loc) · 22.7 KB

How We Use GitHub

This document seeks to outline how we as a community use GitHub Issues to track bugs and feature requests while still catering to development practices & project management (e.g., release cycles, feature planning, priority sorting, etc.).

Topics:

Note

This document is written in the style of an FAQ. For easier navigation, use GitHub's table of contents feature.

What is "Issue Sorting"?

Note

"Issue sorting" is similar to that of "triaging", but we've chosen to use different terminology because "triaging" is a word related to very weighty topics (e.g., injuries and war) and we would like to be sensitive to those connotations. Additionally, we are taking a more "fuzzy" approach to sorting (e.g., severities may not be assigned, etc.).

"Issue Sorting" refers to the process of assessing the priority of incoming issues. Below is a high-level diagram of the flow of issues:

flowchart LR
    subgraph flow_sorting [Issue Sorting in Issue Tracker]
        state_sorting{{Maintainer sorting}}
    end

    subgraph flow_roadmap [Roadmap Board]
        board_refinement{{Refinement}}
        board_backlog{{Backlog}}

        board_refinement-->board_backlog
        board_backlog-- reprioritize -->board_backlog
        board_progress{{Current Sprint - In Progress}}
    end

    state_new(New Issues)
    state_closed(Closed)

    state_new-->state_sorting
    state_sorting-- accepted for work -->board_refinement
    state_sorting-- duplicate, off-topic, support resolved -->state_closed
    board_backlog-- pending work -->board_progress
    board_refinement-- not actionable -->state_closed
    board_backlog-- resolved, irrelevant -->state_closed
    board_progress-- resolved -->state_closed
Loading

Why sort issues?

At the most basic "bird's eye view" level, sorted issues will fall into the category of four main priority levels:

  • Do now
  • Do sometime
  • Provide user support
  • Never do (i.e., close)

At its core, sorting enables new issues to be placed into these four categories, which helps to ensure that they will be processed at a velocity similar to or exceeding the rate at which new issues are coming in. One of the benefits of actively sorting issues is to avoid engineer burnout and to make necessary work sustainable; this is done by eliminating a never-ending backlog that has not been reviewed by any maintainers.

There will always be broad-scope design and architecture implementations that the maintainers will be interested in pursuing; by actively organizing issues, they will be able to more easily track and tackle both specific and big-picture goals.

Who does the sorting?

Core maintainers help with sorting issues, making decisions regarding closing issues and setting feature work priorities, among other sorting-related tasks.

How does issue sorting and board intake work?

New issues that are opened in any of the repositories in the conda GitHub organization are reviewed in the repository issue tracker first. During sorting in the issue tracker, issues are reviewed for the following outcomes:

  • Mitigation via short-term workarounds and fixes
  • Redirection to the correct project
  • Determining if support can be provided for errors and questions
  • Closing out of any duplicate/off-topic issues

The core maintainers are not seeking to resolve issues that arise. Instead, the goal is to understand the issue and to determine whether it is legitimate, and then to collect as much relevant information as possible so that the maintainers can make an informed decision about the appropriate resolution schedule.

Issues can remain in this investigatory phase (e.g., querying the user for more details, asking the user to attempt other workarounds, other debugging efforts, etc.) and are likely to remain in this state the longest, but should still be progressing over the course of 1-2 weeks.

Items are added to the Refinement tab of the Roadmap Board once sorting has concluded and the core maintainer has enough information to make a decision about the appropriate resolution schedule for the issue. Newly opened pull requests are automatically added to the Review board by .github/workflows/project.yml.

Issues that are not accepted for planned work are closed instead (e.g. duplicates, redirects, user errors, resolved support questions, etc.).

Where do work issues go after being sorted?

Once issues are accepted for work, they are added to the "Refinement" tab of the Roadmap Board. After refinement and prioritization, issues move to "Backlog" and then to "Current Sprint" when actively being worked. Issues are closed once the work is complete.

What is the purpose of having a "Backlog"?

Issues are "backlogged" when they have been accepted and refined but are not yet planned into the current sprint.

What automation procedures are currently in place?

Global automation procedures synced out from the conda/infrastructure repo include:

Are there any templates to use as responses for commonly-seen issues?

Some of the same types of issues appear regularly (e.g., issues that are duplicates of others, issues that should be filed in the Anaconda issue tracker, errors that are due to a user's specific setup/environment, etc.).

Below are some boilerplate responses for the most commonly-seen issues to be sorted:

Duplicate Issue 
This is a duplicate of [link to primary issue]; please feel free to continue the discussion there.

Warning Apply the duplicate indicate issues/PRs that are duplicates of another label to the issue being closed and duplicate::primary if an issue/PR has duplicates, this is the consolidated, primary issue/PR to the original issue.

Anaconda Products 
Thank you for filing this issue! Unfortunately, this is off-topic for this repo because it is related to an Anaconda product.
If you are encountering issues with Anaconda products or services, you have several options for receiving community
support:

- [Anaconda community forums](https://community.anaconda.cloud)
- [Anaconda issue tracker on GitHub](https://github.com/ContinuumIO/anaconda-issues/issues)

Warning Apply the off-topic not related to project, discussion is spam, or is otherwise nonsensical label to these issues before closing them out.

General Off Topic 
Unfortunately, this issue is outside the scope of support we offer via GitHub or is not directly related to this project.
Community support can be found elsewhere, though, and we encourage you to explore the following options:

- [Conda discourse forum](https://conda.discourse.group/)
- [Community chat channels](https://conda.org/community#chat)
- [Stack Overflow posts tagged "conda"](https://stackoverflow.com/questions/tagged/conda)

Warning Apply the off-topic not related to project, discussion is spam, or is otherwise nonsensical label to these issues before closing them out.

In order to not have to manually type or copy/paste the above repeatedly, note that it's possible to add text for the most commonly-used responses via GitHub's "Add Saved Reply" option.

Labeling

This section covers the labels and conventions used during issue sorting.

How does labeling work?

Labeling is a very important means for core maintainers to keep track of the current state of an issue with regards to the asynchronous nature of communicating with users. Utilizing the proper labels helps to identify the severity of the issue as well as to quickly understand the current state of a discussion.

Each label has an associated description that clarifies how the label should be used. Hover on the label to see its description. Label colors are used to distinguish labels by category.

Generally speaking, labels with the same category are considered mutually exclusive, but in some cases labels sharing the same category can occur concurrently, as they indicate qualifiers as opposed to types. For example, we may have the following types, type::bug describes erroneous operation, use severity::* to classify the type , type::feature request for a new feature or capability , and type::documentation request for improved documentation , where for any one issue there would be at most one of these to be defined (i.e. an issue should not be a bug and a feature request at the same time). Alternatively, with issues involving specific operating systems (i.e., os::linux relevant to Linux , os::macos relevant to macOS , and os::windows relevant to Windows ), an issue could be labeled with one or more, depending on the system(s) the issue occurs on.

Please note that there are also automation policies in place that are affected by labeling. For example, if an issue is labeled as type::support neither a bug nor feature, is really just a user having questions or difficulty somewhere , that issue will be marked stale [bot] marked as stale due to inactivity after 21 days of inactivity and auto-closed after seven more days without activity (30 inactive days total), which is earlier than issues without this label. See What automation procedures are currently in place? for more details.

What labels are required for each issue?

At minimum, both type and source labels should be specified on each issue before adding it to the "Refinement" tab of the Roadmap Board. All issues that are bugs should also be tagged with a severity label.

The type labels are exclusive of each other: each sorted issue should have exactly one type label. These labels give high-level information on the issue's classification (e.g., bug, feature, tech debt, etc.)

The source labels are exclusive of each other: each sorted issue should have exactly one source label. These labels give information on the sub-group to which the issue's author belongs (e.g., a partner, a frequent contributor, the wider community, etc.). Through these labels, maintainers gain insight into how well we're meeting the needs of various groups.

The severity labels are exclusive of each other and, while required for the type::bug describes erroneous operation, use severity::* to classify the type label, they can also be applied to other types to indicate demand or need. These labels help us to prioritize our work. Severity is not the only factor for work prioritization, but it is an important consideration.

Please review the descriptions of the type, source, and severity labels on the labels page prior to use.

How are new labels defined?

Labels are defined using a scoped syntax with an optional high-level category (e.g., source, tag, type, etc.) and a specific topic, much like the following:

  • [topic]
  • [category::topic]
  • [category::topic-phrase]

This syntax helps with issue sorting enforcement, as it helps to ensure that sorted issues are, at minimum, categorized by type and source.

There are a number of labels that have been defined for the different repositories. In order to create a streamlined sorting process, label terminologies are standardized using similar (if not the same) labels.

How are new labels added?

New global labels (i.e., labels that apply equally to all repositories within the conda GitHub organization) are added to conda/infrastructure's .github/global.yml file; new local labels (i.e., labels specific to particular repositories) are added to each repository's .github/labels.yml file. All new labels should follow the labeling syntax described in "How are new labels defined?". Global labels are combined with any local labels and these aggregated labels are used by the .github/workflows/labels.yml workflow to synchronize the labels available for the repository.

Types of Issues

Standard Issue

Standard issues represent typical bug reports, feature requests, or other work items that have a clear definition and expected outcome.

Epics

Epics are large work items that can be broken down into smaller, more manageable issues. They typically represent major features or significant changes that span multiple iterations or releases. Relate the smaller issues to the epic using the sub-issues feature in GitHub.

Spikes

What is a spike?

"Spike" is a term that is borrowed from extreme programming and agile development. They are used when the outcome of an issue is unknown or even optional. For example, when first coming across a problem that has not been solved before, a project may choose to either research the problem or create a prototype in order to better understand it.

Additionally, spikes represent work that may or may not actually be completed or implemented. An example of this are prototypes created to explore possible solutions. Not all prototypes are implemented and the purpose of creating a prototype is often to explore the problem space more. For research-oriented tasks, the end result of this research may be that a feature request simply is not viable at the moment and would result in putting a stop to that work.

Finally, spikes are usually timeboxed. However, given the open source/volunteer nature of our contributions, we do not enforce this for our contributors. When a timebox is set, this means that we are limiting how long we want someone to work on said spike. We do this to prevent contributors from falling into a rabbit hole they may never return from. Instead, we set a time limit to perform work on the spike and then have the assignee report back. If the tasks defined in the spike have not yet been completed, a decision is made on whether it makes sense to perform further work on the spike.

When do I create a spike?

A spike should be created when we do not have enough information to move forward with solving a problem. That simply means that, whenever we are dealing with unknowns or processes the project team has never encountered before, it may be useful for us to create a spike.

In day-to-day work, this kind of situation may appear when new bug reports or feature requests come in that deal with problems or technologies that the project team is unfamiliar with. All issues that the project team has sufficient knowledge of should instead proceed as regular issues.

When do I not create a spike?

Below are some common scenarios where creating a spike is not appropriate:

  • Writing a technical specification for a feature we know how to implement
  • Design work that would go into drafting how an API is going to look and function
  • Any work that must be completed or is not optional

Working on Issues

How do I assign myself to an issue I am actively reviewing?

If you do not have permissions, please indicate that you are working on an issue by leaving a comment. Someone who has permissions will assign you to the issue. If two weeks have passed without a pull request or an additional comment requesting information, you may be removed from the issue and the issue reassigned.

If you are assigned to an issue but will not be able to continue work on it, please comment to indicate that you will no longer be working on it and press unassign me next to your username in the Assignees section of the issue page (top right).

If you do have permissions, please assign yourself to the issue by pressing assign myself under the Assignees section of the issue page (top right).

Development Processes

The following are practices the conda organization encourages for feature development. While we recommend projects under the conda organization adopt these practices, they are not strictly required.

How should we approach feature development?

For new features, first open an issue if one doesn’t exist. Once the feature request has been accepted (indicated by the issue's status transitioning from "Sorting" to "Refinement"), create a specification to gather early feedback. This can include mockups, API/command references, a written plan in the issue, and sample CLI arguments (without functionality).

What is our change process?

For larger features, break down the work into smaller, manageable issues that are added to the backlog. As long as a feature remains on the roadmap or backlog, do not create long-lived feature branches that span multiple pull requests. Instead, you should integrate small slices of an overall feature directly into the main branch to avoid complex integration challenges.

Should we make unrelated changes at the same time?

When making changes, try to follow the Campsite Rule to leave things better than when you found them. You should enhance the code you encounter, even if primary goal is unrelated. This could involve refactoring small sections, improving readability, or fixing minor bugs.

Code Review and Merging

What are the review requirements?

Standard Review

Most code changes require one reviewer from someone on the maintainer team for the repository. Instead of waiting for someone on the team to review it, directly requesting a review from the person you previously identified to work with is preferred to optimize teamwork. If you paired with them during development, continuous review counts as this requirement.

Second Review

Required only when the code author or the first reviewer feels like it is necessary to get another set of eyes on a proposed change. In this case, they add someone specific through GitHub's Request Review feature with a comment on what they want the person to look for.

What are the code review best practices?

If you are conducting a review, adhere to these best practices:

  • Provide comprehensive feedback in the first review to minimize review rounds
  • Reserve Request Changes for blocking issues (bugs or other major problems) — Select Comment for suggestions and improvements
  • Follow-up reviews should focus on whether requested changes resolve original comments
  • Code should be production-ready and maintainable when merged, but doesn't need to be perfect
  • If providing feedback outside the core review focus (nitpicks, tips, suggestions), clearly mark these as non-blocking comments that don't need to be addressed before merging.

How do we merge code?

If you are the approving reviewer (typically the first reviewer, or the second reviewer when needed) and you have completed your review and approved the changes, you should merge the code immediately to maintain development velocity.

Normally, we use squash and merge to keep a clean git history. If you are merging a pull request, help ensure that the pull request title is updated.