Until a few months, we did not care too much about our (private) issues because we were working in the same office time to time (~ once a week), hence we could synchronize ourselves. Most of the time, we created an issue with a very descriptive title, but the body was left blank or poorly filled. Yet, as soon as we were physically distributed in France and in Germany, we started to write a lot more! We then refined the way we communicate on GitHub.
Crystal Clear Issues
We use GitHub issues to save everything, from ideas to bugs. That is why we carefully sort them with labels. Issue titles must be as short and explicit as possible, which is sometimes tricky but worth doing it. As for the body, we do not follow any specific rule yet, but we have started an experiment with two simple sections: Purpose, that is the aim of the issue, and Proposal, the resolution (if any). This forces us to write full sentences but also to think more about the issue.
Issue title: “Allow filtering by abusing MongoDB querying system”
Along with these two sections come other sections such as Links to provide further information to the issue, Mock-ups for UI/UX improvements/features, and Screenshots when we report a visual glitch. Talking about screenshots, we often use them when we do not craft GIFs to illustrate an issue and get better feedback, quicker. Screenshots and GIFs are like code snippets but for everyone.
We chose not to use GitHub
because, at the time of writing, it was not possible to declare multiple
templates. Instead, we declare templates through preconfigured links (e.g.,
https://github.com/<org>/<repo>/issues/new?body=<markdown>) hidden behind
image buttons in
For each issue, we create one or more Pull Requests (PRs).
On Pull Requests
William wrote how to write Pull Requests a while ago, and we stick to these recommendations. In addition, we reuse the Purpose section introduced previously along with a new one: Features, which indicates implementation details with task lists.
We use task lists for everything and update a PR with new items until it is good
to merge . When we open a PR, we use the
[WIP] prefix in the
title so that everyone knows that it is a Work In Progress. Combined
with labels, this helps differentiate:
- PRs that need a quick review: prefixed with
[WIP]+ needs review
- PRs that need a final review: no prefix + needs review
- PRs that are ready to merge: no prefix + no needs ∗
We also use a lot of screenshots and GIFs to ease code reviews. Talking about reviews, the recent GitHub feature called Reviews is great for approving or requesting changes but it would have been nice to keep the former behavior for hiding comments when the diff changes.
Dear GitHub, we like rockets but we miss the squirrels.
We have a rather short iteration loop for each PR, and this has been drastically eased by GitHub Deployments, a topic we already covered in a previous blog post. Being able to deploy often and on different environments helps us being more efficient when reviewing a PR. This is an important pillar of our communication process.
As a general rule of thumb, be careful when you leave a comment on GitHub. Words or sentences do not often carry emotions or feelings, and you could be rude without even noticing it. Write complete sentences, do not be too short or direct, and use Emoji. Seriously, Emoji are fantastic to convey tones and intents .
In this series, we described how we leverage GitHub Issues to improve our daily communication. We are constantly learning so we might write about this topic again in the future. Meanwhile, tell us how you communicate or how you use GitHub to improve your communication via Twitter or by email.
Yep, we have two more things for you. Enjoy
Bonus #1: Meet
We use hub (
version) to boost our productivity
and create or list issues from the command line but also to open Pull Requests
(William’s favorite feature). You might be interested in more Git / GitHub tips
and tricks by the way.
Bonus #2: Slack, Hubot & Issues
We write minutes and/or create issues after each call and discussion in Slack, but this requires discipline and sometimes, we simply do not do that. After having identified this weakness in our communication process, we wrote a dead-simple hubot script to link Slack conversations with GitHub issues.
By asking our servant
hubot to create a
checkpoint at any
time, we do not loose information anymore. We are still experimenting with this
script, and it might evolve to something more automated in the future. So far,
it perfectly fits our needs!
We use this facility for our private repositories because Slack conversations can only be viewed by people in our Slack organization. We could use it for our public repositories too, but it would only be useful for TailorDev people.