I joined DreamHost about four weeks ago on Feb 6. and am on the
team building a cloud hosting service based on the open source project
OpenStack. I spent the first couple of weeks at the new job doing the
usual sorts of new-hire activities: reading a lot of documentation and
learning my way around the development environment and tool
chain. I’ve done a little bit of work on some internal code already,
and I recently had a good opportunity to start working on OpenStack
itself.
The OpenStack project team was running a coordinated “Global
Hack-In” on March 1st to work on bugs for the upcoming Essex
release. Several members of the OpenStack Atlanta meetup, sponsored
by DreamHost, met to participate in the hack-in as a group. Since we
don’t have official offices in Atlanta, yet, we gathered over at
Duncan McGreggor’s house. Brent Scotten has already posted a quick
recap of the day on the OpenStack blog, but I wanted to go into a
little more detail about my experiences preparing my first patch for
the project because for me this was a new code base on a new project
using new version control and code review tools.
As with many large open source projects, OpenStack requires all
developers to sign a contributor agreement before any patches will be
accepted. I signed the Individual Contributor License agreement
on-line using echosign.com. Then, I added my name and the echosign
signature hash to the Contributors page in the OpenStack wiki and
requested membership in the openstack-cla group on Launchpad. Only
members of openstack-cla can submit patches, though it isn’t clear if
that requirement is enforced automatically by one of the tools or if
it is a convention monitored by the project owners. In any case, my
membership was approved without incident.
Becoming an OpenStack Contributor
The process for signing up to be a contributor to OpenStack isn’t terribly complicated, but there are a lot of steps and the instructions are spread out over a couple of different documents. I took care of subscribing to the required mailing lists and signing the contributor agreement a couple of weeks ago, but I am including those steps here along with the technical stuff I did yesterday, to provide an end-to-end view of the process.Community
The first set of instructions, in the wiki under HowToContribute, explains how to join the OpenStack community. I registered an account on Launchpad, the code hosting service managed by Canonical and used by Ubuntu and other open source projects. Then I joined all of the OpenStack projects (Nova, Swift, Glance, and Keystone). Joining the individual teams under the OpenStack umbrella gave me access to the project mailing lists, so I can eventually participate in conversations about designs and implementation details.Contributor Agreement
Updated: The old CLA process described here using Echosign is no longer valid. Please refer to this wiki page for the current process.Development Environment
I am familiar with source control and virtualization, but not the specific flavors used for this project. My next step was to set up a development environment where I could work on the Nova project documentation, which meant setting up an virtual machine where I could build the project.Virtualbox
My desktop system is running Mac OS X 10.7.3 (Lion), and OpenStack is intended to run on Linux (primarily Ubuntu). To set up an Ubuntu system for the build, I used virtualbox and vagrant. Duncan and Mark had already found a Vagrantfile that would set up an Oneiric image and then use DevStack to deploy all of the parts of OpenStack into the new VM using these chef cookbooks. I saved the Vagrantfile to an empty directory and started a VM using vagrant up. After a short wait while devstack downloaded and installed all of the dependencies, the VM was ready and running a copy of OpenStack based on the git repositories created by the devstack script. The local repositories are created in /opt/stack within the VM, but I wanted to work in a copy that was mounted via NFS from the host OS so I could edit under OS X and build in the VM. I was going to work on Nova, so I cloned its git repository from github and modified the Vagrantfile to have more RAM and so it would mount the directory where my source code was checked out using NFS to /home/vagrant/Devel.
# -*- mode: ruby -*-
Vagrant::Config.run do |config|
sshdir = "#{ENV['HOME']}/.ssh/"
cachedir = (ENV['CACHEDIR'] or "/Users/dhellmann/Documents/Devel/openstack-vm/cache")
checkout = (ENV['COOKBOOKS'] or "/Users/dhellmann/Documents/Devel/openstack-vm/openstack-cookbooks")
# Make /vagrant an NFS mount instead of using the default setting
#config.vm.share_folder("v-root", "/vagrant", ".", :nfs => true)
ip_prefix = (ENV['IP_PREFIX'] or "10.0.5.")
mac_prefix = (ENV['MAC_PREFIX'] or "080027027")
suffix = "100"
ip = "#{ip_prefix}#{suffix}"
config.vm.box = "oneiric"
config.vm.box_url = "http://images.ansolabs.com/vagrant/oneiric64.box"
config.vm.customize ['modifyvm', :id, '--memory', '2048']
config.vm.network :hostonly, ip, :mac => "#{mac_prefix}#{suffix}"
config.vm.share_folder("v-cache", "/home/vagrant/cache", cachedir, :nfs => true)
config.vm.share_folder("v-ssh", "/home/vagrant/.host-ssh", sshdir)
config.vm.share_folder("v-dev", "/home/vagrant/Devel", "/Users/dhellmann/Documents/Devel/nova-docs",
:nfs => true)
config.vm.forward_port 80, 8080
config.vm.provision :chef_solo do |chef|
chef.cookbooks_path = "#{checkout}/cookbooks"
chef.roles_path = "#{checkout}/roles"
chef.log_level = :debug
chef.run_list = [
"recipe[anso::cache]",
"recipe[nova::hostname]",
"recipe[nova::source]",
#"recipe[anso::settings]", # vim / screen / git settings for testing
]
chef.json.merge!({
:nova => {
:source => {
:mysql_password => "secrete",
:rabbit_password => "secrete",
:admin_password => "secrete",
:service_token => "secrete",
:flat_interface => "eth1",
:public_interface => "eth1",
:floating_range => (ENV['FLOATING'] or "#{ip_prefix}128/28"),
:host_ip => ip,
}
},
})
end
end
After restarting the VM (vagrant halt && vagrant up) I was able to
login and switch Nova to use the git repository I had just checked
out:
$ vagrant ssh $ cd Devel/nova $ sudo python setup.py developI encountered some I/O issues using vagrant ssh to connect to the VM, so in the end I switched to using ssh directly via the port that was forwarded using the instructions in the Vagrantfile above and the key vagrant used when setting up the VM.
$ ssh -i ~/.vagrant.d/insecure_private_key -p 2222 vagrant@127.0.0.1
Building the Documentation
The documentation (and test) build for Nova use a local virtualenv created within the source tree. The instructions for creating the virtualenv are part of the Nova Developer Guide. We all had issues with timeouts and installation failures of one sort or another setting up the virtualenv within a virtualbox VM, and I eventually resorted to installing the dependencies into the virtualenv by hand using:$ cd Devel/nova $ source .venv/bin/activate (.venv)$ pip install -r tools/pip-requires (.venv)$ pip install -r tools/test-requiresSphinx and the other related tools needed to build the documentation are installed into the virtualenv so that, with the environment active, it is easy to build the HTML documentation using make:
$ cd doc $ make
Choosing Something to Fix
It takes Sphinx a while to process all of the documentation, and it produced a lot of warnings and errors along the way. Duncan and Mark worked on some bugs in the OpenStack code, but I decided that since I was new to the tools as well as the code-base I would focus on shepherding a small documentation change all the way through the process this time around, to make sure I had everything set up correctly and that I understood the process. Fixing some of the errors in the reStructuredText formatting within the documentation met my criteria nicely.Tracking Changes
OpenStack uses Launchpad for bug reports and task management. Launchpad’s operating model uses “blueprints” to group related related bugs and feature tickets. After studying the errors produced by Sphinx, I decided that there were basically three causes:- Problems in the automatically generated markup used to produce the API guide.
- Problems in the manually written markup of the manual.
- Problems in the manually written reStructuredText within the Nova source code, used when the API guide is generated.
Crafting the Fix
When Sphinx runs to build the Nova documentation, the first thing it does is generate skeleton files for some of the API documentation using a script called nova/doc/generate_autodoc_index.sh. For each module that needs to be documented and for which no documentation exists, a reStructuredText file is emitted containing a header such as:The :mod:`nova.wsgi` Module =========================== .. automodule:: nova.wsgi :members: :undoc-members: :show-inheritance:The result is that even if there is no special local documentation for the module, the doc-strings from the code will be processed and included in the final output. The bug I found was with the way generate_autodoc_index.sh calculated the length of the underline to create the reStructuredText heading. The original version of the script used a single long line of =, but some of the module names were longer than the line. Rather than just extend it, I changed the script to calculate the proper length. Because this was my first patch, I also added myself to the Authors file at the top of the Nova source tree so I would be listed among the project contributors. I committed the change to my local repository, including the blueprint and bug id in the git commit message. At that point I was ready to submit the patch for review.