)
Each year, hundreds of new contributors start working on OpenStack. Most OpenStack projects have mature code bases and contributors who have been developing the code for several years. Ensuring that a new contributor is pointed in the right direction can often be hard work and a little time consuming.
When a newbie asks (a project team lead, jumps in on the mailing list, pipes up over IRC) about how to contribute, the seasoned Stacker will often send them straight to OpenStack Manuals. Why? Because the documentation contribution process is identical to the code contribution process, making it an ideal place to start.
The OpenStack manuals project develops key introductory installation, operation and administration documentation for OpenStack projects. The manuals are a great place to start and provide an invaluable window into each project and how they are operated. This enables the contributor to become familiar with the Git and Gerrit workflow and to feel confident reviewing, responding and reacting to patches and bugs without feeling like they are breaking code lines.
So, from the documentation team to you, here are the Day 0 to Day 5 tips (okay, we’ll be honest, this might work out to more than five days, so take your time!) and links to get you set up during your first week. They’ll help to ensure that by the end of the week, you can feel (and tell your boss!) that you are an OpenStack contribution guru.
Scenario: You’ve been told to get started working on OpenStack, ramp up your contributions and start the journey to becoming a core in a project.
- If you have no idea what this means, or entails, start at Day 0.
- If you understand the concepts, but want to know how to get more involved, start at Day 1.
Day 0:
The OpenStack manuals project provides documentation for various OpenStack projects to promote OpenStack and to develop and maintain tools and processes to ensure the quality and accuracy of documentation.
Our team structure is the same as any other OpenStack project. There is a Project Technical Lead (PTL) who ensures that projects and individual tasks are completed and looks after the individual contributor’s requirements, if any. The PTL is the community manager for this project.
A team of core reviewers work with the PTL. Core reviewers are able to +2 and merge content into the projects for which they have core status. Core status is granted to those who have not only shown care and wisdom in their reviews but have also done a sufficient quantity of reviews and commits.
The OpenStack manuals team looks after the repositories listed here.
There are no restrictions on who can submit a patch to the OpenStack manuals. If you are looking to get started, the Contributor Guide is your source for all information.
To begin contributing, use the First Timers section to set up your accounts, Git and Gerrit. We treat documentation like code, so we have the same process as development. We also recommend that you join the documentation mailing list (and introduce yourself with a few lines) and join the #openstack-doc IRC channel on Freenode.
Day 1:
You have successfully setup your Git and Gerrit workflow and you know what commands to execute to submit a patch for review.
We recommend tackling a low-hanging-fruit bug. These bugs have been triaged by the documentation team and have been designated a “quick fix.” The issue should be described within the bug report or within the comments. However, if you do not believe you understand the bug you can do one of the following:
- First, join the OpenStack Documentation Bug team. Set the status of the bug as “Incomplete” and ask the reporter to provide more information.
- If the bug addresses a problem with project specific documentation, contact the Documentation Liaison for the specific project.
Our documentation is written in RST, so ensure that you have an appropriate text editor to assist with your formatting and syntax. You can also find the guidelines for the general writing style that all documentation contributors should follow to ensure consistency throughout all technical publications.
From here, you can either patch the bug and apply the fix, based on the workflow described in the First Timers section, or you can review some of the patches from other people. Reviewing documentation patches is one of the best ways to learn what’s in the guides.
Day 2:
Reviewing documentation can be confusing – people are replying to the patch with requests, bug reports and maybe even content specifications.
At the beginning of each release cycle, the project teams work out their key deliverables at the Project Team Gathering (PTG). This immediately impacts the documentation – what changes upstream must change in documentation. This usually comes to the documentation in the form of a bug report. The project will report a bug to the OpenStack manuals team by either tagging DocImpact in the commit message of the original development patch or by filing an entirely new bug with a request for documentation to be updated.
While the project teams work out their key deliverables, the documentation team also has a chance to decide on what deliverables need to be met within the guides. This might relate to technical debt, archiving, or perhaps even a mass change that must occur across all of the guides. This work is tracked through a specification.
All patches up for review should link to a specification, bug report, or, at the very least, have a detailed commit message following our Good Practice guidelines.
When reviewing the patch, ensure that the committer has explained why they fixed the problem and ensure that what they say matches the output. If you need to build the documentation to review properly, you can use our build tools, or you can use the gate jobs, gate-[REPO-NAME]-tox-doc-publish-checkbuild, to check the build in your browser.
Here are some guidelines to remember when reviewing someone else’s patch: http://docs.openstack.org/contributor-guide/docs-review.html
Day 3:
On Day 1, you pushed up your first patch. You made iterations based off requests from other individuals and now, according to the guidelines, your patch can merge with the required +2, +1 and +2a. Do not be concerned if your patch is not ready and merged by Day 3, however. Getting a patch reviewed and then merged can often take time.
Safely merged, you need to know where to go next. If you would like to work on a specific guide or guides and you don’t know how to get involved, see Day 4.
If you are interested in staying involved but really don’t know what you want to do, we recommend you continue fixing bugs. You can find the list of all bugs that have been confirmed or triaged by the OpenStack manuals team here.
Do not work on any bugs that are labeled “New” and do not have “Confirmed” or “Triaged” in the Status column or any bugs that already have an assignee.
Day 4:
One of the things you might come across on the mailing list and in the Contributor Guide, is the mention of specialty teams. To ensure that each of our guides are looked after and the bugs against the guides are dealt with, the documentation team has assigned specialty team leads. You can find the list of each specialty team lead here.
To get more involved in an individual guide, contact the relevant individual listed. Each team often has projects happening that require new contributors. You do not have to specialize in only one guide.
Day 5:
Now that you’ve spent your first week working within the manuals, you have several possible routes to take from here. You can:
- Continue working with the documentation team and gain insight into how OpenStack is installed, used, and administered by fixing bugs and working with the specialty teams.
- Find more documentation outlets. Each development project has their own developer-tailored documentation. You can find that, and more information, at: docs.openstack.org/develop/PROJECTNAME
- Start working on your project of interest! All you need to do is clone the relevant repository and get started!
Good luck!
Join us in #openstack-doc on Freenode to say “hi” and have a chat!
If you choose to contribute to another project, please always come back and document the new changes so that the code can be used by admins.
Cover Photo // CC BY NC
- From zero to hero: Your first week as an OpenStack contributor - February 10, 2017
