The way you report issues has changed
You know the drill, right? You go to report an issue and you’re asked to decide whether it’s a bug or a feature you’re reporting. You decide quickly, click through and regardless of what you’ve selected, you’re faced with the same form.
The guidance you’ll need is there but it’s a bit busy and it’s also disconcertingly easy to ignore it or just delete it all. Besides, you’re busy, you know what you want to say and so you do and then you get back on with your job and await a reply.
For our part, we’re happy to read your report but often, we don’t have all the information we really need to progress. The first time you hear from us might be us checking in to see which version you’re on, but you reply. And then? More waiting.
It’s with this in mind that we decided to make use of the new feature offered by GitHub - Issue Forms (currently in beta).
To many, the introduction of mandatory fields might sound like a no-brainer but for us, this is shiny and brand new. We are now able to ensure that issues that have the information we need to progress, get through first time. Anyone submitting an issue without those finer details will be prompted by validation. And the result? Less waiting!
You can currently have a look and see what you think of the new templates, now implemented for all bug reports and feature requests. We took our time selecting the fields that would need to be mandatory as we felt that the contributor would be happy to be guided in breaking down information into separate fields when reporting bugs. Currently, feedback has been super positive and as a team, we are very happy indeed.
Pull Request bot will help you make your PR more excellent
We love your work. You have been quietly submitting PRs for some time now and we have been sometimes quietly and sometimes with much discussion reviewing them but we know that when you submit a PR, you want to know what is going to happen with your work.
We can write blog posts and we can give talks, and we do all that, but we know that to enhance the experience for a new contributor, it’s a good idea to let people know at the point of submission exactly what will happen at each stage of the review process.
We were reluctant to introduce our Friendly Umbraco Robot in the first place, preferring to do everything person-to-person and keeping those friendly vibes going. Person-to-person doesn’t always scale, so we opted to bring the bot to life and hand over some of the responsibilities in the realm of information delivery over to said bot.
Thanks to the success of the bot on the repo, we’ve decided to expand the role to include an explanation of the steps that are being taken in the review process.
Our friendly bot won’t only be telling you what’s going on; the bot will also be providing guidance to the person reviewing your PR in the form of a checklist.
This allows your reviewer to ensure that they have all the information they need and that they have done all the necessary things to ensure your PR can be merged without any problems. As a bonus, you might realize that you forgot something and can immediately amend your pull request, win-win.
Feature requests start out as discussions
A bit of Umbraco history: when our contributor list was smaller, and the numbers in only double digits, a feature request might have looked like a chat over a beverage with a few other devs at a meetup. Fast forward a few years and the Umbraco hashtag becomes a great way for contributors to discuss features globally.
With the introduction of the GitHub issue tracker in 2018, there was now a place where contributors could discuss features, get input from HQ, seek answers from each other, and design solutions together.
The only issue (ahem, pun) was that the issue list itself has been a place where everything lives. We can label things to categorize, and that has helped us respond to issues appropriately but otherwise, feature requests live alongside bug reports and security issues.
The comment format of input is fine, it can be a little restrictive too and we find that it’s all too easy for a feature request to get lost among the noise. Time we trialed exciting-new-GitHub-feature number two!
GitHub Discussions allows for feature requests to begin their lives as a discussion. The discussion doesn’t live on the issue tracker but in a separate area where contributors and HQ staff can get together and throw around ideas until a plan is agreed upon. This will give you, and indeed us, a chance to consider all the variables before you go off and do the work of submitting a PR.
We’ve already been experimenting with discussions on one of our repositories and the experience has been really good so far.
When a discussion becomes a plan, we are able to transfer the plan to the issue tracker as an up-for-grabs issue that is ready to be worked on. This is a fantastic way to ensure that the time you spend working on your PR is used wisely and that you have absolutely everything you might need before you get started.
Additionally, we think Discussions will also be a great place to create “Super Issues” like the ones we’ve had for accessibility and Angular decoupling. These issues usually live for a very long time until all subtasks are done. Creating a discussion for them also makes it easier to comment in threads to talk about specific subjects.
Next steps
In the coming days, you might notice your inbox filling up with GitHub notifications from us. Do not be alarmed. We’re not just changing the way feature requests are submitted moving forwards, we will also be moving feature requests to GitHub discussions retrospectively. We’ll be doing this to ensure that your feature request is given the opportunity to live in this new world, where contributors can see it and can add their thoughts.
Older feature requests that would be currently being considered for closure, given their inactive status, will be given new life and in the months after Codegarden, we’ll take a look at which are active and which are inactive and make a choice as to which will stay open and which we can close.
As ever, no closure is final. You’ll always be given the chance to resurrect your feature request if you believe it is still relevant.
While we’re getting these changes in place, we’ll undoubtedly learn more about how to make the experience as friendly as possible. We’re sure you’ll have some feedback on these changes as well, so why not start a GitHub Discussion when you do! We’re happy to listen, provide guidance and tweak things where needed.
This is just the first step and in the future we’ll be making similar changes for repositories other than Umbraco-CMS to streamline the process across the board.
We hope you’re as excited about these changes as we are. We have lots to look forward to in the coming months and we’d like to take this opportunity to thank you all for your continued collaboration.
If you’d like to know more about the issue tracker, be sure to attend our talk “We’ve all got issues” at Codegarden on Friday at 14:45 CET. If you’re yet to register, sign up here 👇
