Issues, Labels and Templates

The Foundation uses GitHub Issues and GitHub Project to manage all of its projects and functions. The purpose of this document is to explain how to use GitHub in line with the Foundation’s guidelines.

Open

We use GitHub issues for everything in the Foundation (GitHub Projects provides a mechanism to coordinate issues, but GitHub issues are the core unit of defining work in the Foundation).

We work remotely so good clear communication through issues is important to the smooth running of the Foundation.

Epic: We call an issue and epic when it contains a list of sub-issues, epics are used to connect together a set of related issues. You might use an epic to define the issues needed to be done for a sprint, you might use an epic to collect a set of similar types of issues together, e.g. all the issues related to marketing a release. An epic is just a collection of sub-issues.

Issue Labels

Every label in the foundation is lower case and uses - instead of _

Every project is free to choose it’s own set of additional labels but these labels are common for every repository in the Foundation.

Issue Contents

Every issue whether it’s an Epic or a Individual Task needs to contain at least 3 fields before it’s assigned to someone else to work on.

Why: Why does this need to be done? (If this is a sub-task of another issue, can just say “Sub-task of #”
What: What do you expect as the deliverable for this issue, short one sentence summary?
Scope of work: Breakdown of the tasks needed to complete this issue (usually with checkboxes)

Draft Issues

Issues labelled as draft are places to put ideas so they are recorded and not at risk of being lost.

Draft issues don’t have to adhere to the above format.

Draft issues are not intended to be worked on or even communicated to others.

If you want to assign an issue to someone or ask for their help to flesh out the contents of an issue it must not have the label of draft and it must contain at least the min content above.

Issue Communication

All conversation regarding an issue should remain on the issue.

If you need to have another conversation outside of the issue, the summary of that conversation needs to be added to the issue.

PM’s are responsible for summarizing any lengthy conversation by updating the issue description with the current state of the conversation and any decisions made.

Anyone should be able to know the entire state of an issue by reading the issue, it’s he PM’s responsibility to ensure that is true.

Issue Escalation Policy

We are a remote first, highly distributed organization with many people who are volunteers, some staff that are full time and some staff that are part-time. It’s extremely important to the smooth running of the Foundation that communication keeps on flowing.

We have a strict communication policy to ensure the conversations are kept moving forward and projects do not stall.

• If you are tagged in a conversation you should respond within 24 hrs.

• If you are assigned a ticket and the ticket is needs a response from you, you must respond within 24 hrs.

• If you are assigned a ticket and the ticket is labelled needs-response, and you do not respond within 24 hrs an email is sent to the Executive Team cc'ing you. The Executive Team will then work to ensure the ticket is answered ASAP.

If you need a response from someone on a ticket the best thing to do is to:

• Tag them directly in the issue clearly asking the question you need a response on.

• If they do not respond, assign the issue to them and make sure it’s only assigned to them.

• If they still do not respond, label the ticket as needs-response and our systems will escalate the issue automatically.

If you have been assigned a ticket to respond:

• Try to respond as quickly as possible.

• Once you’ve responded assign the ticket back to the person who next has to take action, usually the person that assigned the ticket to you.

Issue Templates

To find out complete information about issue templates and issue template forms read this https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser

By default when someone clicks New Issue it creates a Blank issue.

Open

But if you want you can setup Issue Templates so when you click new the user is presented with a few pre-defined types of issues they can create

When they create an issue using one of these templates it pre-fills some content in the issue which you can use to encourage people submit an issue in a particular format.

You can setup Issue templates by adding markdown files to the .github/ISSUE_TEMPLATE folder in the repository e.g. https://github.com/Green-Software-Foundation/writers/tree/main/.github/ISSUE_TEMPLATE

Or you can try using the editor which let’s you setup from the website directly, like so: https://github.com/Green-Software-Foundation/writers/issues/templates/edit