GitHub workflow procedures

About this document

This document describes the GitHub workflow and "procedures" that should be followed by maintainers.

GitHub labels

We have a set of basic labels that are common to all repos and should be used to communicate and/or flag issues and PRs. It's a clear and quick way of understanding the current status of something, help filtering and also triage what's it about.

On PRs they are even used by the change log generator to properly update the change log with bugs, enhancements, breaking changes, etc. That's why it's vey important that all those are properly labeled from the moment they are created.

The Home project has several others that are used to classify the group the issue belongs to (like tools, a specific class library,...). There are also a few that should be used to flag them to the community with a call for action like "good first issue", "trivial", "feeback requested".

To summarize it's very important and makes everyone life easier if the labels are used properly.

GitHub issues

Upon a new issue being raised, it should be properly labeled and, if possible/relevant, a follow up comment should be added. This is useful to show developers that we care, that the project is active and also helps the flow of the next steps, which is someone eventually pickup the issue, reply to it, make additional testing or start working on it.

When a maintainer self-assigns an issue or assigns it to another team member the appropriate flags should be managed. This provides follow up to the community and prevents that several developers invest their time working on the same task, possibly duplicating work and wasting time, which leads to frustration.

As it's made abundantly clear on all repos that GitHub issues should not be used to ask questions. For that, developers are encouraged and should use the Discord channels. They are better served there by having a quick reply, reach-out to everyone in the community, have a better experience and it's usually more convenient. Having said that, issues raised to ask questions should be directed to Discord and closed with an appropriate and polite message. The exceptions would be when the user can't use Discord (because of company firewall rules, some regions in the world have access to social network block) or a quick reply does it, which is more efficient.