Last weekend before the end of the internship has just gone and my main thought is "but... I've got a bunch of things to do still!".

That's not necessarily a bad thing in the sense that I somehow expected it to happen: one of my goals in going through this internship was to learn how to be an active contributor, but also to remain one after it finalizes.  So, yeah, I'm dedicating this last days to completing as many pending tasks as I can, but I also know that some of them will be part of upcoming ideas/projects I want to carry out after next Tuesday. 

For example, one of the things I worked on was trying to improve the navigation of the OpenStack API reference page by creating linkable anchors or permalinks to each API listed there.  The task looked simple and necessary, but I clearly underestimated the evil power or Maven, one of the main tools we use to build docs, and spent a lot of time testing builds, tags, attributes and black magic to no avail yet.  The good thing is I learned a ton, the not so good one is I'm gonna have to write some Maven code to allow this feature and this will possibly take some extra days to be added to the page.

Talking about Maven, I'm yet to post the second part of Doc for code and Doc as code - Part I, where I'd like to delve a little bit more on OpenStack docs and tools.  It's still a draft and I haven't had the time to finish some details.

One thing I will not miss at all is this. Blogging.  Don't get me wrong: I do think is a wonderful idea that interns post about their experience.  I absolutely enjoyed reading all my fellow interns blogs, but this is just not for me.
I never really had or maintained a blog simply 'cause... I didn't have to.  I never thought that I had anything to say publicly that somebody else could find interesting.   I know those are not the only reasons to write a blog, but then, I had none.
When blogging became part of the internship's work, I thought it was the best reason I could ever find.

My number one error was to have chosen Dreamwidth as my journal service. I totally support the concept, ideas and spirit behind it, but posting has been just painful. 
Mine is a free account, so I shouldn't complain about some features that are offered only to paid or premium ones (such as using Google Analytics), but the fact of not being able to upload small pictures, the outdated look (is it just me?) despite futile customization and, worst of all, that terrible HTML editor made it all less appealing. 
I will not close it for now, but will probably migrate it to a self-hosted platform in the future.  I'd still love to spread the word about FOSS communities and technologies.

Anyway, I can't completely blame DW for my own incapacity to get ideas and thoughts out of my head, it's just I don't think they'll survive the harsh reality.
Some weeks ago, while going to the movies with my mom, she mentioned that I used to fall asleep while watching any of the Star Wars movies on the TV (the first two were released before I was born), and to be fair, I can't remember having watched them in full, at least during recent years, so that made me think that, maybe... I wasn't a complete geek after all, Your Honor!
Then I recalled we were going to see The Hobbit, so... I guess I'm appealing the veredict?  Hey, don't judge, I'm sleepy.

Are you an Active Project Contributor for OpenStack? Have you made a contribution to any of the OpenStack projects lately? Well, check your email if you have! Chances are your vote is awaiting.

While the next OpenStack release, Grizzly, will be out there as the latest stable branch next April 4th, OpenStack officially announced, by the beginning of March, the PTL and Technical Committee Election period, which means that all current project's leaderships will be replaced (or renewed), for the upcoming development cycle and following release, Havana.

So, the first week was time for nominations: all contributors who wanted to run for a Project Technical Leadership needed to send an email to the development mailing list and present themselves and their candidacy. Certainly the idea is that, even when anyone could propose him/herself as a candidate, contributors with a considering involvement with the project and the team are the ones expected to have the best chances to be elected.

These are all our projects' candidates:

- Russel Bryant
- Michael Still
- Henry Nash
- Dolph Matthews
- Eoghan Glynn
- Julien Danjou
The following remaining projects only got one nominee, so they became Havana PTLs automatically:

Cinder >> John Griffith
Glance >> Mark Washenberger
Heat >> Steven Dake
Horizon >> Gabriel Hurley
Oslo >> Mark McLoughlin
Quantum >> Marck McClain
Swift >> John Dickenson
To be eligible to vote you need to be an OpenStack member with a tangible contribution made during the current cycle. You should then receive an email (one per each project you contributed to) providing you with a personal link to submit your decision.

I had completely forgotten about it, but apparently I made a contribution to Nova and Keystone (possibly some fix for the docs section), so it is very possible that some other new contributor is not aware of this or simply forgot too.

If you're sure you contributed to any project (not just reviewed something), but did not received any emails, get in touch with the Infrastructure team guys at #openstack-infra, they'll certainly help you out.
Polls will end today at 23:59 PST, so there are still a few hours left, results will surely be ready soon after that. Not too late, go check your mail!

Update March 15th:  Yay! Results are ready, this is the message sent by Monty Taylor, who was managing the polls:

"The PTL elections for the Havana cycle have completed. The new PTL's are:

Nova: Russell Bryant
Ceilometer: Julien Danjou
Keystone: Dolph Matthews


As a side note, we had over 50% participation in each of the three
elections, which I have been told is actually a really good turnout."
It was announced several weeks ago: a group of passionate OpenStackers would gather, starting Feb 25th, for a Sprint Book to come up with the highly expected Operations Guide.

Certainly the Book Sprint methodology is pretty interesting: a group of people get together to write a book in a week or less with the guide of a facilitator. The idea is that, on day one, you start with nothing and, by the end of the last day, you end up with a published book.
And I said "interesting"...? Scary!

Despite not being part of the fellowship, I couldn't help feeling anxious for them. It was a bit of a daunting quest: OpenStack is big and has the complexity of every new technology. There is a lot to read and to ask, and to test and break before you can tell you know enough to try to explain it to somebody else, but the team was skilled, experienced and fully armed with sticky notes and markers.
Still, five days seemed literally crazy to put together all the info, explain the basics about cloud computing and its requirements, go from innocent commands to the troubleshooting depths of a cloud without grieving for all those fallen lines that could not be kept for the sake of edition and... Okay, I might be going overboard, but I've heard it was an intense week, to say the least.

These are our daring participants:
  • Diane Fleming --OpenStack Docs writer
  • Tom Fifield --OpenStack Docs contributor, Australia
  • Anne Gentle --OpenStack Docs Coordinator and writer (I'm honored to have her as my OPW mentor)
  • Lorin Hochstein --Cloud expert
  • Adam Hyde --FLOSS Manuals founder and Book Sprint facilitator
  • Jonathan Proulx --OpenStack Admin at MIT
  • Everett Toews --Developer Advocate at Rackspace
  • Joe Topjian --Cloud Admin and designer, Canada
Still doubtful?

They totally made it
, and the feedback is terrific! (they even used an open source tool as the editing & publishing platform!)

[In case you cannot see the embedded video, check here]
I'm happy they nailed it, but most of all, I feel grateful. Not just because of the great effort they've gone through or because there is now more quality documentation to relay on, but also because they've created this to and for the community: it's not a static doc, it's planned to grow and be improved, an asset we can all contribute to.*

There are several remarkable things about the work itself. I personally enjoyed (as many others will, I guess) the Use Cases and Tales from the Cryp^H^H^H^H Cloud chapters --it's easy to feel lonely in a server room when it's all about getting things up and running, and those sections not only help you remember you're not alone and others have been through the same, but also show what's behind FOSS technology: hard-working, committed people.
Something this achievement demonstrates quite well. Congratulations!

*You can also purchase a paper copy here, all the proceeds will go to the OpenStack Foundation :)
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 "your      _username"
    tux@meow:~$ git config --global "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

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://

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.
Picking up the general topic from the previous post, it's time now to get more specific. Currently I'm working on the API docs' bug backlog, which goes from fixing errors and updating current data to adding support to new extensions to the OpenStack API Reference site.

OpenStack has developed a wide and still growing collection of RESTful APIs, which are sets of functions and specifications that provide the users and administrators with a simple and lightweight interface to interact with other complex systems or libraries, such as the different components of the cloud computing environment:

So I had this vague idea of what an API was and what it was used for, but the term "RESTful" was new to me. Given the latter and the fact that the following info is available more extensively and accurately browsing the web, I'll try to keep it simple, mainly for other "uncultured" like me.

REST stands for Representational State Transfer, and while it's an architectural style for Web services, it is not a standard. That's perhaps the reason why today any API is easily (but sometimes wrongly) called RESTful. The term was first utilized by Roy Fielding, who's one of the authors of the HTTP protocol.
Despite not being a standard, there are good practices to consider and, furthermore, there are constraints that define the basic qualities of the RESTful style. The six constraints are: Uniform Interface, Stateless, Cacheable, Client-Server, Layered System, Code on Demand (optional).
I will not describe them here, as they possibly deserve an exclusive post, but if you're really interested you can read Fielding's dissertation, which is the original source. It would be interesting instead to mention the goals of this type of architecture, which sound quite familiar:
  • Scalability of component interactions
  • Generality of interfaces
  • Independence of components deployment
  • Intermediary components to reduce latency, enforce security and encapsulate legacy systems
I found it not surprising that OpenStack had chosen this API model. I've gone through several docs and links, but the best explanation of how this design model works without being terribly complicated was found in this tutorial (also found this one, a bit more orthodox, but you can fork it in GitHub!):

"...The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.
RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations."

Here's a slightly modified example of how a RESTful API works in OpenStack:

The user sends a HTTP request, using the GET method, to the API. In order to do that, the user will need the API's URI (Uniform Resource Identifier, which is a string of characters to identify a resource, i.e.: "http://hostname:port/v2.0/users").
The API relays the request to the final system, in this case Nova (or Compute Node), which will process the request and send back a message (response) through the API to the user.
This is rather a simple example of how it would work, but there are others in which you'll also need to provide a request body in JSON or XML format (Openstack APIs support both). Response bodies, if available, will also be returned in those formats.  The HTTP methods to use, depending on what you need to do, are GET, PUT, POST and DELETE.

The way to interact with a RESTful API is up to the user: many at OpenStack use cURL, which is a command line tool, and will be maybe the best option if you're comfortable with text terminals.
A request to list all the IP addresses of a server will look like this on cURL:

$ curl -v -H "X-Auth-Token:XXXXXXX" http://localhost:8774/v2/openstack/servers/1/ips

... and this is what you'd get in response (JSON format):

"addresses": {
"public": [
"version": 4,
"addr": ""
"version": 6,
"addr": "fe80:0:0:0:0:0:c0a8:6402"
"private": [
"version": 4,
"addr": ""
"version": 6,
"addr": "fe80:0:0:0:0:0:c0a8:6402"

If you prefer a graphical interface, there are several to choose from, like the Firefox RESTClient (it's an add-on):

OK... perhaps I've rambled too far without going very deep in many of the subjects of the post: some of them are so relevant to today's software architecture that probably being exhaustive could take too long, but the idea was to remain simple, as much as I could.

Although far from "restful", I feel the research on all these concepts has given me a better understanding of what I'm documenting and why it matters.

Why doc?

Jan. 17th, 2013 11:16 am
It's been hard this time to pick just one topic to post about, as these last two weeks have been an intense journey through many of the tools and work-flows one needs to contribute to OpenStack. And I do realize that it was just the tip of the iceberg, but hey, that's what we're here for!
I thought then of posting about some of those things, such as Git -which is common to most of the projects-, bug fixing, XML, Doc building, etc. But then I saw that I was missing the reason for all these tools: Documentation.
Yes, it may not sound as exciting as developing cutting edge applications, but guess what? They too need to be documented. You can't just go happily through a technology world that gets more complex everyday without reading, at some point in your life, a simple tutorial, a user guide, an administrator manual, or even heavier code documentation.


I saw this cartoon a few years back, and its truthfulness made me laugh then.   I recalled it a few days ago, when wondering about how valuable was the technical documentation considered by the rest of a software community.  I still laughed, but this time I also worried. I'm not that pessimistic, but having experience from working in other IT areas (the customer support scene is scary, but often true) I can tell that, well... there's a reason why we laugh.

There are several versions of this comic, but in all of them the documentation part is empty. Perhaps this prejudice comes from outdated development methodologies (especially for proprietary soft, I dare to say), but I think today no one really expects a neat and functional piece of software to speak on its own to other coders, users or newbies.  Unless you wrote the code for yourself, to be its only end user, the "no document" approach is clearly preposterous.

That is especially true in FOSS communities: many of the most interesting software projects today are built by the fingers of many contributors, some of them real geeks, but most of them with different backgrounds and skill levels.
It also goes beyond that.  If you want your software to be successful, or used (or even purchased), what would you tell to your potential customer?:  "Specs? Requirements?  Oh, here's the code, it's so brilliant you don't even need a manual"?

These days I could gladly see that even when some development myths may remain, they are to disappear.  An OPW mentor made a great point when she mentioned that docs even could be seen from the marketing side "as sort of part of a ladder of engagement".
I got it then.  It all comes down to a communication matter.  And docs make a great channel.
Sorry, I really couldn't have chosen a less original title for this first post, but though the real subject will be a different one, I still wanted to wish all the best for the starting year to the poor soul reading this.
It's actually the GNOME's Outreach Program for Women what I wanted to comment this time. The 2013 round will start tomorrow, January 2nd, finishing on April 2nd.

The first time I heard of the program was when some girl in a mailing list for Linux users I'm subscribed to sent a message about it. As someone who always enjoyed working with free and open source software (and also benefited from it), I though it was really cool, but then the questions popped in my head: "Do I have the necessary skills to apply? How can I really contribute to a project if I'm far from being some kind of tech-guru, or an experienced software developer?"
I convinced myself then that it was simply not for me, and forgot about the matter, to keep on working as a full-time IT tech for private corporations with little interest in FOSS.

This year - well... past - was different. I didn't feel technically ready yet (will I ever do?), but I tried not to make self-assumptions and just got in touch with the organizers, mentors and coordinators. I took some time to read about all the offered projects and each community need, and soon found out that it would be hard to pick just one project, since all organizations offered a wide variety of amazing things to do (and learn, my favorite carrot).
I lurked on several IRC community channels and not only confirmed that people at FOSS are the coolest, but also that all questions are welcome! There's always someone willing to help, and even if you don't have any questions, you can learn a couple of things, and maybe someday, be the one who answers.

Long story short: I sent my last-minute application for the OpenStack Documentation project, not without the help and support of coordinators and other fellow applicants. All of them and all the stuff I learned those few days made me realize not only how worthwhile the application process was, but also that even if not chosen for the internship, I felt now welcome to get involved and contribute any way I could.

Please, don't miss the feeds at Women in Free Software planet, where other OPW interns will be sharing their knowledge and experiences.

April 2013



RSS Atom

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Sep. 26th, 2016 10:25 am
Powered by Dreamwidth Studios