The Good Docs Project recently achieved a significant milestone: releasing version v1.0.0 of our project. It was an exciting moment for our community of contributors dedicated to improving the quality of software documentation by sharing best practices — the first time we felt confident putting our production-ready documentation templates into the world for other software projects to review, use, and help us improve.
Organizing and executing a release of this magnitude requires extensive planning and sophisticated project management tools. Luckily, our community uses GitLab, so we had everything we needed at our disposal.
In this article, we'll explain how we used GitLab to meet our goal of bringing Version 1.0 (codenamed "Capilano") to the world. Our release process consists of four general phases:
We'll share how we use GitLab in each of those phases to achieve a successful project release.
Scheduling a release
The Good Docs Project releases template updates twice a year: on June 15 and December 15. Each of our releases receives both a number and a codename in honor of a famous bridge (because we're "bridging the documentation gap for our users"). Last December, for example, we issued Version 0.3.0, codenamed "Brooklyn Bridge" release. In June, we finished Version 1.0.0, which was codenamed "Capilano" for a bridge in Canada). And now we're starting work on the Dragon release, which gets its name from a bridge on the River Han in Vietnam.
Our release schedule prioritizes work time over work scope. We set goals we wish to accomplish with every release, then use the release deadline as a motivational tool to get projects done. However, we don't delay releases for a particular release initiative per se. Instead, we try to accurately scope and track our release initiatives to ensure they complete in time for their desired release.
Planning a release
For the first month of our six-month release cycle, each of The Good Docs Project's working groups or teams determines initiatives for the cycle. They usually hold an initial brainstorming session, which involves using a synchronous collaboration tool (like Miro) to determine which ideas to include as official goals for the release. But after confirming and committing what we want to do with each release, we migrate all those objectives to GitLab, where we communicate them to the rest of the community. That process generally looks like this:
- Open an issue in a release's respective repository and we tag it with the milestone for that release
- Attach scoped labels to indicate which working group is assigned to that task
- Assign an initial health status of "On track"
- Assign the issue a weight to indicate its importance
Then, in a general community meeting where we end the release planning process, everyone identifies what they'll commit to, and we begin using the milestone to track progress and a global project board to track the health status when we do stand-ups to report on progress.
To prioritize effectively, we draw on guidance from our team of template product managers, who perform extensive user research into the templates our users or potential users think we should add to the roadmap. We attend conferences and engage with both technical writers and developers to hear what they want from our product. This team of product managers then distills this information into a long-term product roadmap that informs which template issues are strategically important to our project. We then translate that roadmap into issues in our project backlog.
Tracking a release
Gaining access to GitLab's project management features was one of our primary motivations for adopting the platform in the first place. These features allow us to track and monitor our progress toward a release. We love that with GitLab we can manage multiple sub-projects and repositories under our organization, but still view all the issues on a "single pane of glass." This allows working groups and teams to work in their individual repositories, but gives us a high-level overview of their work at the organizational level, using features like milestones and scoped labels.
To track our releases, we configure a project milestone that runs for the full release time period. The milestone shows all the initiatives we're working on, as well as our progress toward each on an organization-wide burndown chart. We use scoped labels (labels that can only be assigned to one value at a time) on each issue to track which working group is working on that initiative. We also use GitLab's health status feature to track whether the initiative is on track or at risk of falling behind schedule. On top of that, we create a project board that helps us visualize all the project's active issues and initiatives, filtered by each working group. Our project board provides insights into the work each group is doing and gives us a sense of the release's overall progress toward our release goals.
These boards are a focal point of our weekly general meetings. We review the milestone and project board, then check in with working group and team leads to make sure their work toward the release is going well. These meetings are opportunities to identify potential blockers preventing (or threatening to prevent) the work from getting done — or to communicate if any of our earlier estimates need to be adjusted. We build some flexibility into our release planning and tracking processes in case we need to make mid-release changes or course corrections. For example, we determine which individual template projects we'll add them to a release *during the release process itself, rather than during the release planning stage we descibed earlier. Since those projects are dependent on volunteer work that can't always be controlled by the project leads, we wait to officially add them to a release until we can be certain a template project will be ready for release day.
Release day
When release day finally arrives, our Tech Team meets to tag the release in the templates repository and build our artifacts, including all our zip files and tarballs for our templates. To do that, the team:
- Verifies that all merge requests are complete
- Creates a tag for the templates repository for the main branch and adds a tag message indicating it is for a release
Adds a release title, tags it with our milestone for that release, confirms the date, and adds the release notes (using our community's own release notes template, of course) by using the
Create Releasebutton on the release screen - Creates the release; GitLab generates all the files from our repository, including zips, tarballs, and JSON artifacts
- Publishes a link to our release and the artifacts on our website
We try to ensure we've recognized and tagged every project member who contributed directly to the templates release. That includes people who wrote templates, improved existing templates, or created examples for our templates. Then, the Tech Team publishes the artifacts and release notes to our website and publishes an announcement to all our internal and external communication channels.
We believe it's important to take breaks. For that reason, our project always takes a three-week break after release day. For those three weeks, we encourage all our project members to get some well-deserved rest and relaxation. We don't hold any meetings during this time, and we encourage people to only communicate lightly with other project members.
Then we regroup in July or January — and start the release process all over again!
It's not too late to join our next release and experience this process firsthand. Just visit The Good Docs Project community page to learn how to get started.
The GitLab Open Source Partners are building the future of open source on GitLab. Connect with them on Gitlab.com.
