GitHub is where most of our work is recorded, reviewed, and decided. This page is a starting guide for new team members on what we expect from you day to day. It applies to everyone here at FlowFuse organization
For our wider communication norms, see Communication.
Why we use GitHub
We are a distributed company, so we write things down where they stay searchable. GitHub holds our code, but it also holds the discussion and decisions behind it: feature ideas, bug reports, customer requests, design work, art requests, and the handbook itself.
Two habits follow from this:
- Work in the open. Default to a public issue or pull request rather than a direct message.
- Keep context with the work. If a decision happens in Slack, summarize it in the relevant issue that was created so the next person can find it.
Repositories you should know
| Repository | What it holds |
|---|---|
FlowFuse/flowfuse | The FlowFuse platform. Product bugs and feature requests are tracked here. |
FlowFuse/website | Our website, blog, documentation, and this handbook. |
FlowFuse/admin | Internal operational checklists and requests, including new repository requests. |
You do not need to watch every repository. Watch the ones tied to your work and rely on mentions for everything else.
The vocabulary
- Issue - a unit of work, a bug, or an idea. Most conversations start here.
- Pull request (PR) - a proposed change to files in a repository, including handbook pages. Changes get reviewed here before they merge.
- Label - a tag used to categorize and filter issues, for example by area or priority.
- Milestone - a group of issues delivered together.
- Project board - a board view across issues, used for planning.
- Review - feedback on a PR: approve, comment, or request changes.
- Mention - writing
@usernameto pull someone into a thread. Mention people deliberately; it is our main signal that something needs attention.
Notifications
GitHub sends a lot of email by default. Tune it so it stays manageable.
Under Settings → Notifications:
- Route participating and mention notifications to your FlowFuse email.
- Turn off email for everything you are only watching, and read those in the GitHub inbox instead. Then work from these three views rather than your inbox:
- Pull requests that mention you
- Issues that mention you
- Pull requests that need your review
Bookmark all three. The GitHub notification inbox also works well if you prefer a single list.
Respond to mentions and review requests within two business days. If you cannot give a full answer in that time, reply with when you will or that work is in progress.