Skip to content

How Issues are Managed

Alex Suraci edited this page Jan 17, 2019 · 3 revisions

The Concourse project uses GitHub issues to keep track of bug reports and feature requests. This document exists to shed some light on the project's workflow and explain some of the things you may observe as you request features, report bugs, and keep track of the issues that you care about.

GitHub issues should not be used for questions or support - please use the forums instead!

Common Labels

Classifications

enhancement

This label is applied to issues that are requesting or proposing new functionality.

Having this label does not imply advocacy for the issue's feature -- it's just a classification.

bug

This label is applied when the issue describes something is either not behaving as intended or has regressed from previous versions (in which case it may be given an additional regression label).

Bug reports should have clear steps to reproduce. If an issue is reported without an easy way of confirming that it's a bug, it may end up being closed with no resolution.

Anything with a bug label is somewhat objective, and should probably be fixed as soon as there's a clear idea of how to do so.

Communication

good first issue

This label is applied to issues that are small enough in scope that a first-time contributor could relatively easily start working on it and submit a pull request.

help wanted

This label is similar to good first issue but is a bit more of a cry for help. It may be an enhancement that a lot of people want, or a bug that needs more information and testing in order to fully understand.

high impact

Substantial features that enable new workflows or have wide-reaching implications are given a high impact label.

High-impact features are treated with great caution. Implementing feature after feature is something to be avoided in service of keeping Concourse simple and focused. For this reason, it's very important that high-impact feature requests spend a good amount of time on context-building, not just solution-building.

Feature requests with a high impact label are often left to stew for a while until there is a solid understanding of the problem space and until there's a good idea of how many people would be affected by it (ideally in a good way). This is done by pattern-matching feature requests/bugs to find common ground, or by kicking off an RFC to work on a proposal.

If an issue falls within scope of an already-existing RFC or high impact issue it may be closed in service of centralizing discussion on the RFC or other issue.

Concourse's scope is naturally very large -- every developer should use a CI system -- so it's important to take special care when making any high-impact change, in an effort to keep Concourse simple in spite of the many different ways that people will want to use it. The Concourse ethos is to measure ten times and cut once.

anti/* (anti-patterns)

These labels are used to call out common anti-patterns that should generally be avoided. They are big and red and scary and are typically a bad sign, though they don't outright shut down an issue - they may sometimes be used as a warning shot when the issue touches on tricky aspects that should be carefully avoided.

Each label is further described in the Anti Patterns document.

wontfix and invalid

The wontfix label is applied when there is no intention to follow through with the issue, probably because it just isn't a priority. This is typically applied to stale issues.

The invalid label is similar but is more specifically for issues that appear to not actually demonstrate anything wrong with Concourse itself (either working as intended or a problem with the user's environment, not Concourse).

Process Lifecycle

size/* (complexity estimates)

These labels are a rough estimate of the complexity for the issue, implementation-wise. They are typically applied to issues that are prioritized in the backlog of one of our projects.

triage

This label is applied to new issues automatically and is removed once someone has looked at the issue and handled it accordingly (perhaps by replying or just adding more descriptive labels).

paused, documented

These labels are applied to issues as part of our development workflow at Pivotal.

  • paused means we started on an issue but had to put it down temporarily to work on something more emergent.

  • documented means we've written release notes (and any additional documentation) necessary for the change.

Epics

The concourse repo projects are used for grouping together substantial tracks of work that span many GitHub issues. This is for discoverability and to show progress somewhere easy to find.

Each of these projects only has two columns: "Planned" and "Done". Issues are automatically transferred to "Done" when they are closed.

Milestones

Milestones are used for release planning. They may sometimes be given a due date to reflect the estimated time of the release. This is more to set expectations and is never a firm date.

Pivotal Backlogs

The Concourse team at Pivotal uses organization-wide projects as part of our day-to-day engineering/backlog workflow.

An issue will be entered into one of these projects when we're considering implementing it ourselves. From there the issue may progress through the following project columns:

  • Icebox: issues that are on the backburner, in no particular order. They may have not yet been validated and there may be no plan to work on them yet.

  • Backlog: issues that are prioritized for being worked on by our team.

  • In Flight: issues that are actively being worked on.

  • Done: issues that are either complete (if they were worked on) or otherwise closed.

An issue may be removed from a project and optionally given a good first issue or help wanted label. This would typically happen if we don't expect our team at Pivotal to get to it any time soon.

Staleness

When an issue is inactive for 60 days, a stale bot will drop by, tentatively add a wontfix label, and leave a comment asking if anything can/should be done to keep the issue moving along.

After seven more days of inactivity, the issue will be closed. This is really just to keep the project tidy. Sometimes issues pile up because they're duplicates, or a feature request that didn't gel with anyone, or a one-off bug that no one else was able to reproduce (perhaps an issue local to the reporter's environment).

It takes a lot of time for a human to go through and constantly check for these situations, so we've removed the humanity from the process and left the dirty work to a robot. Please don't feel offended if you feel an issue has been unjustly closed. Feel free to open another issue and reference the original instead!

You can’t perform that action at this time.