I have been trying to improve our development experience by putting things together and create processes for our most common tasks taking advantage of the automation and features from GitLab and other technologies.
Today I’m going to propose the workflow for project & release planning for individual projects and for GNOME as a whole in the least time-consuming, most automatic and simple way I could come up with.
It’s my hope that this proposal will improve our contributor experience, reduce time spend on tracking issues, improve communication between teams such as design and engagement, increases exposure for PR, and finally, shorten the feedback & review cycle.
- Reduce the need to explain our plans to just once. Including to our managers, release team, release notes writer, downstreams, users, other developers…
- Attract contributors to work on what we consider priority for the project and help maintainers on make those happen.
- Guide the current contributors in the short term and long term vision of the project.
- Expose to the engagement team our plans to allow PR being done.
- Shorten feedback cycle with designers and users.
- Reduce the gap between GNOME release and downstream releases by allowing downstream better preparation upfront.
- Manage effectively the explosion of issues and prioritize what’s actually wanted and doable.
Workflow from written plan to implementation in individual tasks in individual projects. For example Nautilus does nothing, and others like ToDo, Calendar and Boxes use the Kanban workflow. The proposal written here is for the higher & overview levels.
Only three, but important:
- As developers we focus on development, not paper work. This proposal should make things easier and less time consuming in the long term for you and the project contributors, not the opposite. Otherwise, I would need to revisit the proposal.
- Short & concise, but complete. If there are requirements for a proposal, it’s not important if it’s written just with 2-4 words each, what’s important is that the list contains all of them.
- Realistic. It’s better to be short on promises but deliver them than the opposite.
Writing down project plans
One thing that applies to all of us is that writing plans down feels heavy. However it’s usually not about writing per se, it’s more about thinking what the format should be, what you actually need to write, etc. — Formalizing a plan is not easy.
To alleviate that, I created an issue template on GitLab to be used when you need to set up a plan. Copy it inside your project as “.gitlab/issues_templates/Epic.md”. It’s called “Epic” as a term that comes from Agile development. An Epic is a plan/task that goes across releases or development phases. Tasks that are achieved in one release are also fine, given our long 6-month cadence.
However, what’s important about epics it’s their meaning. They mean that the task fulfills three things:
- Well scoped
- Have an achievable end, when is considered done & completed
Specifically, they are not moon-shots. e.g. Improving Nautilus performance is not something that is well scoped and it doesn’t have a end date, therefore doesn’t fit as epic. In doing so, we avoid ideas that are unrealistic and also we don’t set the wrong expectations to other contributors, other teams, users and even more important, to ourselves.
You can see how it works for Nautilus in these two examples, adding a testing & performance framework & adding an action bar. And also we can consult epics across GNOME by an assigned label that I created for the GNOME group. It’s possible to see that the planning worked well for evolving the action bar design to something completely different than the original proposal thanks to the feedback and design contributions from several parties after exposing our plans in a easily reachable way.
With this we can answer what is the vision and priorities for GNOME projects individually or as a group.
Tracking & planning
It’s a fact that we cannot really handle all the issues that are reported to our projects, to the point navigating them stop making sense. Not only that, contributors & potential contributors usually don’t know on what to work or the priorities we have as a project. Or even worse, contributors providing patches that are not a priority so they are languishing for months with no review. I’m pretty confident to say that we lose contributions by not having clear plans.
So how about flipping the approach and pick the tasks/issues that we really care about and tag them? Something like a “backlog” of issues that fits well in the project, and even better, we can group them in two groups to expose our short-term and long-term project vision at the same time.
For that, we will use GitLab labels. They allow to query, edit and subscribe to the tasks assigned to them and display in a convenient UI. For that purpose I created two labels in the GNOME group, “Deliverable” and “Stretch”:
- Deliverable: Short term vision. Planned for a moving target of aprox. 2 releases.
- Stretch: Long term vision. Planned for a moving target of aprox. 4 releases.
When a new issue is created, read it and if it’s something really wanted, doable and scoped tag it and move on. The rule of thumb is that you only tag issues that either someone works on them or you will eventually need to. Later on you can select the label to query them and do “sprints” of development, which it’s quite useful to focus for some days on code rather than project management or bug triaging, and also you can point to that label to other contributors to know what they can work on.
Everything here is automatically handled, when tasks are completed or closed they will disappear from the list of open issues, and we can sort them by closed date or other values that allows other teams and people to check the status. We no longer have to track tasks manually or put some strange wiki attributes and we can query all plans across GNOME.
Note that we are not pinning plans to a specific release. Also note that these are a moving target, that means that if there are 2 releases that the project was not maintained, they “do not count”. Let’s not kid ourselves, we are a contributor driven project and with our past roadmaps we have seen specific dates being more a failure than an achievement.
With this proposal, we allow for a more flexible project planning where time is not as much a constrain but rather we just tell what the project vision for the future is and what our priorities are. Designers, contributors, engagement team, users and downstreams now can provide early design advice, contributions, PR exposure and feedback & testing respectively.
Now we can query these, both for individual projects or across projects at GNOME:
- The short term vision (epic + deliverable).
- The long term vision (epic + stretch).
- The short term tasks and fixes (deliverable).
- The long term tasks and fixes (stretch).
Pinning to a specific release
We have achieved quite a few goals so far with this proposal, but we are missing to help a few people and teams, including the release notes writer, video making creator and release team for each release, after all what gets consumed is what’s released.
Here is the only case that a specific date will be set, aka a “milestone”, that are also available for the GNOME group. A milestone is only added if it’s sure that the task/issue/feature/fix will happen for that release, most probably after it’s implemented and merged, or if it’s considered a true blocker. In doing so other people can rely on those items, and maintainers only commit to a specific date when they are sure the fix/task is gonna happen or has happened.
With this proposal poor souls *cough* Allan *cough* hunting maintainers down to get what major changes happened in the projects for release notes won’t be necessary anymore. And other poor souls *cough* Bastian *cough* trying to make the release video won’t be as frustrated. The release team can also track better the releases.
Now we can answer what is going to be included in the release 3.30. or which major tasks are going to be included in 3.30 (epic + 3.30).
Cross project GNOME initiatives
We now can plan and track tasks per project, and that’s already quite good! However, one of the questions we are missing to answer is, how about GNOME itself? Are there goals (or epics) for GNOME as a whole?
We had have a wiki page called initiatives in the past for that, and that was exactly its purpose. However, it was missing some bits to actually make it successful…
Apart of the missing automation of tasks and tracking, the way initiatives were defined were quite loosely, and most of the times there weren’t people in charge of making sure they happen. So the processes were quite cumbersome and the exposure of the initiatives were quite low, resulting on not very successful stories around that.
With those problems in mind, this proposal moves our initiatives effort to GitLab as a similar work flow than “Epics for GNOME”, provide templates for people to create them and automate as much as possible their tracking and delivery. For that purpose:
The project GNOME Initiatives has been created. The wiki with instructions is shown, and there is a template for creating an initiative.
Where the template will provide sections to fill, so there’s not need to think about the format and they will guide to provide useful information for others.
A label per each initiative is also created , so we can track the tasks assigned to a single initiative across projects. And last, we provide the same work flow and requirements as epics, so other people and teams know what to expect and can help make it happen or check the status easily.
For example, the first initiative created is to integrate Flatpak + CI for development of all core apps and newcomer apps. Quite useful! Go check it out as an example, and also take peek of it (not yet finished):
Big thanks to Jordan Petridis and Ernestas Kulik for being part of making this proposal to happen, I own them a drink!
In case it was not clear, I’m writing and doing all this work so neither me in the future or you have to, the whole point is that you just need to click 2 buttons and write 10 sentences and be done with it, if that’s not the case then I will need to improve the proposal.
Also, take this as an starting point, not as an end. There are not many new ideas here, more like trying to make them convenient, easy and straightforward once together. However believe me that I spent several days reading planning documentation and other issue trackers to make sure this is the best approach for GNOME. I’m looking forward to hear feedback and ideas from all and incorporate them, specially for the different teams at GNOME. This is going to be successful only if most of us at the core projects use it, and I think it will be beneficial for all of us.
And lately, consider that planning is not only about a maintainer and its code. A project at GNOME is also designers, is also engagement, is also release team, is also downstreams, and is also any potential contributor/tester/designer/marketing person that is not involved yet because we don’t expose our projects enough.