UPDATE: As part of the celebration for the OpenStack 5th Birthday, both Angus Lees and I organised a ‘Newbie OpenStack Contribution’ workshop. Angus kindly shared the slides from the presentation, take a look at this excellent guide for new contributors. Check our Australian OpenStack User Group Meetup site for photos from the night.
I’ve been promising to do a newbie workshop for the Australian OpenStack User Group (AOSUG) on “Introduction to OpenStack Contribution” for a while now. Along with my AOSUG colleague Angus Lees (previously Google IP network developer, Rackspace and Openstack Neutron contributor, Docker and OpenStack container guru extraordinaire).
The best way to learn is not simply reading and trying yourself, nor is it just asking questions online (although all these are great!) Just like in school, the best way to learn something new is to get together with a bunch of people and work with each other to help, learn and follow a set of processes or work through some problems together. An OpenStack User Group is just the place for that!
As a way to kick-off, I thought it best to gather my notes, links and thoughts here. Now first caveat. I’m no programmer-superstar. My mate Angus yes, me – I’m a hack! I’m one of these strange people that just likes to figure out how everything works. I’ve figured out some basics, but am still learning. So who better to guide you? Now, allow me to let you in on some of the basics that (I think ) I’ve figured out about OpenStack Contribution…
This is not an OpenStack introduction, or beginners “What is for OpenStack?” If you’re asking those questions this is best addressed first off the mark! Secondly, why contribute? Well apart from the warm fuzzy feeling of participating in a project that will save all of mankind as well as many other altruistic reasons, some could also be more beneficial for yourself. Outcomes such as ability to create both code and documentation that benefit your own project or organisation, as well as technical self-development and career development. Of course these all go hand-in-hand with creating a better outcome for all involved in the OpenStack project too. Share and share alike!
Basics To Begin With
For starters, we’re assuming that you have at least a concept of what most of these mean: git, gerrit, sed, vim, emacs, python, bugs, blueprints, review, workflow. If you don’t, click the links to find out more!
If you don’t have a working knowledge of all these, then you need to be at least willing to invest a little time to learn! You don’t need to be an expert, but by all means it pays to have a fairly solid knowledge of linux bash, git and some sort of terminal dev environment such as vim or emacs; as well as the overall OpenStack development workflow. You can always put in more time to learn more vim and git magic! You are also going to be comfortable having had many of these components running on your linux system. Whilst the OpenStack project can be contributed to from any system with the right setup, this configuration is out of scope for this guide. Most guides assume you are running Ubuntu linux local, or at least have that running in a VM or cloud resource that you do your development from. If you are using OS X or Windows, then please look elsewhere for guidance.
One of the most complicated aspects for the newbie OpenStack developer, is the setup. Sure you may be keen to get cutting some Python code, adding your input to some document changes, perhaps weighing in on some Blueprints, or comment on some code… but “whoa, hold up there partner!” Let’s get some things straight, you need a bunch of setup and a basic understanding of the whole fairly complex, mind-bending process of OpenStack development workflow; and general aspects of open source code contribution first.
Even if you’re just wanting to participate in documentation contribution, you need to understand the development process for OpenStack. Why? Because even the OpenStack Documentation projects require a knowledge of the dev process including git and gerrit, as well as some other Documentation Project specific tools such as Oxygen and tox.
Essentially whether you want to contribute to the OpenStack Documentation, or actually want to contribute towards actual OpenStack Code, Bug Triage, or Reviews; the best way to start is on the Documentation Project. This is because not only is the OpenStack Documentation Project tightly coupled with the OpenStack code development process, but also the Documentation contributors understand this can be a common place to start, so can be a little more lenient and helpful for the newbie OpenStack contributor. There is an excellent guide that jumps straight into the specific OpenStack code contribution, but it does assume you have some knowledge of the workflow, testing and gating process; which we’re assuming you’re not experienced with just yet.
With that in mind, following are some links on both OpenStack Contribution as a Developer and contribution towards the Documentation Project. Read them all!
OpenStack Contribution Link Swarm
OpenStack Docs Project
OpenStack Documentation HowTo
How to Contribute to OpenStack
Developer’s Guide – Getting Started
Contribute to OpenStack Documentation – Video Walkthrough
OpenStack Development and Contribution Workflow – Video
How to Contribute If You’re a Developer – OpenStack Wiki
OpenStack Documentation Source and Target Locations
Editing DocBook with vim
Getting Started with OpenStack Contribution
The following list is taken from Developers Getting Started and Documentation HowTo for First Timers guides, both which should be reviewed and contain excellent and complimentary introductory setup and basic first steps. In summary, the basic steps to begin contributing to OpenStack (same setup for code contribution and document contribution) are:
- Register as a Foundation Member (“Individual Contributor” is best way to start)
- Agree to “Contributor License Agreement”
- Setup your Launchpad account
- Create and configure your Private/Public Key Pair for Launchpad
- Setup and Configure your local dev environment (could be cloud or VM based dev environment, but we’ll just assume and call it “local” no matter what you’re using)
- Clone a repo
- Checkout a bug
- Contribute, make comments, include commit message
- Commit change
- Send to gerrit for review with git review
- Check, follow and action requests further review requirements in gerrit/Launchpad
SSH Key Tips
The biggest challenge can be troubleshooting a Private/Public key mismatch with your local setup and what SSH Key is configured in Launchpad. It is recommended to create a specific key pair for OpenStack development that you use with both Launchpad and review.openstack.org. With this in mind, be sure to configure your .ssh/config file, replacing the host section with the correct review.openstack.org host, based on the “Using Custom SSH Key” section in the Launchpad SSH Key Pair Guide.
Additionally, if you or your organisation is using OpenStack, at some stage you will need to leverage the OpenStack APIs. In particular you ideally want your apps to leverage the cloud capabilities of OpenStack, rather than just scripting or orchestrating workloads on top of OpenStack. It is this approach that really unlocks the capabilities of cloud and OpenStack to their fullest potential. If you ‘re a Python programmer, using the Python Command Line Tools, Python API Bindings and Python SDK are arguably much simpler and more powerful to work with than OpenStack command-line tools or the REST API. It should be obvious that improving your Python skills to enable you to not only debug or develop OpenStack code, but to also leverage the capabilities of the Python API bindings and SDK; would then enable your OpenStack skills to be leveraged in a far more powerful way.
In fact the most powerful (and possibly least leveraged) component of OpenStack is the APIs. Not only are they very powerful component, they offer the most versatility and capability. The Horizon User Interface and the CLI in fact do not leverage as much deep capability as the APIs themselves! Clearly if you or your organisation are using OpenStack, leveraging the Python Command Line Client, or even better the API via the Python SDK is the only way to go.
Further OpenStack Developer Information
OpenStack Lists -for our purposes, best ones to subscribe to are Community & OpenStack-docs
OpenStack Branch Model
Learn Gerrit Workflow in Sandbox
OpenStack Bugs – Wiki
OpenStack Contributor Documentation
OpenStack Python SDK
Addendum – Python Programming
If you want to take things further and get right into developing and OpenStack code contribution, start getting stuck into Python.
Python Beginner Programming Link Swarm
Python for Non Programmers – Books, Links & Tutorials
Python for Beginners – Getting Started
Best Way to Teach a Beginner to Program
Learning Python Guide
Best books/courses for learning Python – Quora
Learn to Program in Python – Codecadamy
Learn Python The Hard Way by Zed Shaw
Dive Into Python 3 by Mark Pilgrim
Python also has a strong set of introspection features as discussed in this StackOverflow answer
Go through the Learn to Program Coursera classes Learn to Program: The Fundamentals and Learn to Program: Crafting Quality Code by Jennifer Campbell and Paul Gries
The Python Tutorial found in the Python Documentation
O’Reilly Python ebooks
Python Essential Reference by David Beazley
All images are courtesy of Wikimedia Commons, except where noted are Copyright Marten Hauville. They are all taken from the beautiful mountains surrounding Vancouver, in British Columbia; and are in recognition of the recent OpenStack Vancouver Summit held there.