[personal profile] ladquin
One of the aspects that I find appealing the most in regards to working for OpenStack Docs is the way document contribution is handled.
Developers are pretty much used to a more or less strict tool workflow to get their code added that may include: error reporting/submission, triage, coding, testing, review, merge, etc. And, of course, each software group or community has its own.

In OpenStack there is a well-established workflow for code contribution, and, neatly, it's the same if you want to delve in docs. You can even see this footer message in the official Docs page:

"Documentation treated like code, powered by the community - interested? Here's how to contribute."

That HowTo page is really very clear and complete, but getting started is maybe the hardest part for newcomers, as there are a few extra, but simple, steps to follow. Here's just a simplified recipe, so you have an idea*:
  • Sign the Contributor License Agreement.
  • If you don't have one already, create a Launchpad account. All bug reports and Blueprints are tracked there, so this is not optional. Also at this step you should add your public ssh keys (you can add as many as necessary).
  • While in Launchpad, request to be added to the OpenStack-CLA group. The request will be approved and then synched with the system. May take a few minutes. You can also join any other OpenStack group in Launchpad.
  • You can continue with the creation of a GitHub account, where all repos are stored. You'll need to paste the same ssh keys you added to Launchpad here too.
  • Install git. Chances are that you've already got it if you're a developer, but otherwise just run this in the command line:
    tux@meow:~$ sudo apt-get install git 

At this point you should also configure git to allow you interact with repos and, more importantly, submit your code for review (that's why ssh keys were added; they do the authentication job). So then do:
         tux@meow:~$ git config --global user.name "your      _username"
    tux@meow:~$ git config --global user.email "your@e.mail"

    If you forget later the username and email, you can run this to get them:
    tux@meow:~$ git config --list
    Or simply check the file ~/.git/config.

The same way, you're going to install git-review. However, before doing that, bear in mind that you'll also need pip, which is a tool to install Python packages, so first run this if pip's not installed:
    tux@meow:~$ sudo apt-get install python-pip 
And then you'll be able to do:
    tux@meow:~$ sudo pip install git-review 

Now, let's say you spot a typo in a manual --this was actually my first contribution. Typos are far from being important, but are good exercise to get the beginners through the workflow.
If not already there you can report the bug in Launchpad (the Docs section is appropriate), and then you'll use git to clone (copy) locally the repo where the file is to work on it. Let's say the repository is "compute-api":

tux@meow:~$ git clone https://github.com/openstack/compute-api.git

That will create a folder named "compute-api" in the current directory. Move to that folder:

tux@meow:~$ cd compute-api

The following command will test your ssh keys and then ask for your Launchpad credentials:

tux@meow:~$ git review -s

If after entering your credentials you get a "Permission denied", go to the OpenStack Gerrit site, log in (same Launchpad ID) and verify that your account info matches your ~/.git/config file. You can also verify that your ssh keys were added correctly to Gerrit. If your credentials are accepted, you may still get another enigmatic error: "We don't know where your gerrit is" (Ha! like I do!). Just do:

tux@meow:~$ git remote add gerrit ssh://your_username@review.openstack.org:29418/openstack/compute-api.git

This will add a remote git to Gerrit (and also create a hidden folder and file in the directory). I think most of the errors and issues are faced at this point, and the most likely reason can be a simple ID mismatch between the communicating interfaces.

Now you're free to work on the repository to fix the bug. I've chosen a doc repo, but with the workflow we've gone though, you can contribute to code, testing, etc.

It's strongly advised to create a new branch with git before saving any changes. You'd normally use the bug number or blueprint to name the new branch:

tux@meow:~$ git checkout -b bug-12345

Here's when the real Documentation work is addressed, but though there are specific tools and conventions to work with, it is really treated and built as code. I'll elaborate on that in Part II.

So then, you fixed the typo and verified that the Documentation still looks ok. Now, you want to propose that modification to be reviewed and approved before it's merged to the main version (or the one you chose to work on). That's what we use Gerrit for: you cannot just merge or push your changes without other (more experienced) member's approval.

Honestly, there's a lot to add about git itself that can make your life easier, but there are already a lot of interesting and more complete posts by fellow interns at Planeteria WFS. One of the commands I find useful the most is "git status": it not only tells you if you are on a master branch or a new one, but also shows what's been done on that particular branch (deleted/modified files, additions, etc).

So, once you're ready to submit your patch, while standing on the parent folder ("compute-api"), run:

tux@meow:~$ git commit -a

This will automatically open a console editor (nano, vi, etc ) with a commented message including the list of files for that patch. You need to fill the git commit message with specific data, such as the reason of the change, main functionality, bug number, etc (an empty message aborts the commit). Once completed, save the file and close the editor.

The patch was not submitted yet. The next command you should run is:

tux@meow:~$ git review

Be careful not to use 'review -s', or you will be trying to merge other people's patches --which of course will lead you to an error.

If any of the steps fails, you are allowed to curse my name, but better yet, join any of the one of the OpenStack IRC channels and ask there, there's hardly out there a more welcoming-and-kind-with-newcomers community.

This topic looks old compared to other stuff I've been doing with Documentation, but I really enjoy the fact that it's handled as code, and even when I have barely talked about it, this is the way to started with any contributions to OpenStack.

*I've deployed git and pip in Debian and Ubuntu this way. Steps may vary for other distros. There are some people out there who, after severe pain, made it work in Windows. I seriously recommend to use at least a tiny vm with any Linux flavor.

April 2013


Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Sep. 28th, 2016 06:47 am
Powered by Dreamwidth Studios