The painful process of submitting your first patch to OpenStack

Recently, I built a Python tool for SurveyMonkey that hooks up our Github projects to our Jenkins instance by asking a few command-line questions (wizard) and generates the Jenkins job automatically. It literally takes less than a minute to get projects hooked up with the code building on every change / pull request, run tests, coverage, etc. and you don't even have to visit Jenkins' irritating UI.

A lot of the heavy lifting is actually done by Jenkins Job Builder (JJB), a great tool created by the OpenStack InfraTeam on which I rely on. During the development process I did small improvements to JJB and submitting a patch back to OpenStack as a way to say thank you sounded like a no-brainer. Little did I know.

The 27 steps to OpenStack contribution

If I had an OpenStack instructor, this is what I would have been told:

Protip

The following steps illustrate my process on how I eventually succeeded at submitting a patch and I'm confident this is how most wannabe contributors would do it.

1. Fork the Github project
2. Hack a patch and submit a pull request.
3. See the pull request being automatically closed with the message:
   
   openstack-infra/jenkins-job-builder uses Gerrit for code review.
   
   Please visit http://wiki.openstack.org/GerritWorkflow and follow the instructions there to upload your change to Gerrit.
   
   
4. Visit the GerritWorkflow page.
5. Convince yourself that you don't want to read the novel entirely, CTRL+F for smart keywords.
6. Run out of ideas, give up.
7. Regret, grab a Red Bull, get back to it, read the novel.
8. Create a Launchpad.net account (I had one, password recovered).
9. Join the OpenStack foundation (wat?).
10. Locate the free membership button and click Join Now!
11. Skip the legal stuff and find the form fields, name, email...
12. Wonder what "Add New Affiliation" means. Skip and submit your application.
13. Oops, you need to add an affiliation. Add an affiliation.
14. You also need to add an address. Address of what? Run the following Python code to find out:

    python -c 'import random
    print random.choice(["address-of-yourself", "address-of-affiliation"])'

15. Finally submit your application form and wonder what they could possibly do with your address, it should work.
16. Return to the GerritWorkflow page.
17. Ah, upload your SSH key to Gerrit.
18. pip install git-review
19. Skip the instructions that don't apply to you but don't skip too much.
20. Try something. Didn't work? That's because you didn't skip enough.
21. Understand that you must run git commit --amend because you need a Change-Id line on your commit message which gets generated by git-review.
22. Finally, run git review! (like git push, but pushes to Gerrit)
23. Oh wait, now you have to figure out how Gerrit works. It's a code review tool which UI seems to have been inspired from the Jenkins one. Curse.
24. <squash the numerous understanding-Gerrit-steps into one>
25. Tweet your experience.
    
26. Hope that someone sees your patch.
27. Iterate with friendly OpenStack developers.

Actually, step 27 is a lot of fun.

Dear OpenStack

Many contributors probably just gave up and you may have lost valuable contributions. This is not a rant about Gerrit itself (ahem), I do understand that it is a code-review tool that you prefer over Github pull requests and that each tool has its learning curve. But you must smoothen the first-commit-to-Gerrit process for newcomers, one way or another. Please consider these improvements:

• reduce the heavy bureaucracy
• replace Launchpad's sign-in with Github's, the source is cloned from there anyway
• write instructions geared towards developers in a hurry, they can later become better users by reaching out for help to OpenStack developers, as I did.
• (my favorite) convert a Github pull request into a Gerrit review and submit the link on the pull request before closing it.

Please make your on-boarding pleasant, everyone will be rewarded.

Love,
Alex