Training at EuroPython 2014 Making your first contribution to OpenStack

OpenStack logo

Last week I ran a 3-hour training on how to get started contributing to OpenStack at EuroPython. The aim was to give a high-level overview of how the contribution process works in the project and guide people through making their first contribution, from account creation to submitting a patch.


The session starts with an extremely fast overview of OpenStack, geared toward giving the participants an idea of the different components and possible areas for contribution. We then go through creating the accounts, why they're all needed, and how to work with DevStack for the people who have installed it. From there we finally start talking about the contribution process itself, some general points on open-source and OpenStack culture then go through a number of ideas for small tasks suitable for a first contribution. After that it's down to the participants to work on something and prepare a patch. Some people chose to file and triage/confirm bugs. The last part is about making sure the patch matches the community standards, submitting it, and talking about what happens next both to the patch and to the participant as a new member of the community.


During the weeks preceding the event, I ran two pilot workshops with small groups (less than 10 people) in my local hackerspace, in preparation for the big one in Berlin. That was absolutely invaluable in terms of making the material more understandable and refining the content for items I didn't think of covering initially (e.g. screen, openrc files) and topics that could use more in-depth explanations (e.g. how to find your first task), timings, and generally getting a feel for what's reasonably achievable within a 3-hour intro workshop.


I think it went well, despite some issues at the beginning due to lack of Internet connectivity (always a problem during hands-on workshops!). About 70 people had signed up to attend (a.k.a. about 7 times too many), thankfully other members of the OpenStack community stepped up and offered their help as mentors - thanks again everyone! In the end, about half the participants showed up in the morning, and we lost another dozen to the Internet woes. The people who stayed were mostly enthusiastic and seemed happy with the experience. According to the session etherpad, at least 5 new contributors uploaded a first patch :) Three are merged so far.

Distributing the slides early proved popular and useful. For an interactive workshop with lots of links and references it's really helpful for people to go back on something they missed or want to check again.


The start of the workshop is a bit lecture-heavy and could be titled "Things I Desperately Wish I Knew When Starting Out," and although there's some quizzes/discussions/demoing I'd love to make it more interactive in the future.

The information requested in order to join the Foundation tends to surprise people, I think because people come at it from the perspective of "I want to submit a patch" rather than "I am preparing to join a Foundation." At the hackerspace sessions in particular (maybe because it was easier to have candid discussions in such a small group), people weren't impressed with being forced to state an affiliation. The lack of obvious answer for volunteers gave the impression that the project cares more about contributions from companies. "Tog" might make an appearance in the company stats in the future :-)

On the sign-up form, the "Statement of Interest" is intimidating and confusing for some people (I certainly remember being uncertain over mine and what was appropriate, back when I was new and joining the Foundation was optional!). I worked around this after the initial session by offering suggestions/tips for both these fields, and spoke a bit more about their purpose.

A few people suggested I simply tell people to sign up for all these accounts in advance so there's more time during the workshop to work on the contribution itself. It's an option, though a number of people still hit non-obvious issues with Gerrit that are difficult to debug (some we opened bugs for, others we added to the etherpad). During one of the pilot sessions at the hackerspace, 6 of the 7 participants had errors when running git review -s  - I'm still not sure why, as it Worked On My Machine (tm) just fine at the same time.

Overall, I'm glad I did this! It was interesting to extract all this information from my brain, wiki pages and docs and attempt to make it as consumable as possible. It's really exciting when people come back later to say they've made a contribution and that the session helped to make the process less scary and more comprehensible. Thanks to all the participants who took the time to offer feedback as well! I hope I can continue to improve on this.

Leave a comment

Adventures with Steam on Linux Today: Mark of the Ninja doesn't start

I've been getting back into PC gaming for the last couple of months, and that has involved a lot of checking out what Steam on Linux looks like nowadays (i.e. playing lots of games). Most of the time everything works just fine and smoothly, but sometimes there are hiccups and yesterday I was motivated to learn how to debug them. Our story begins: Mark of the Ninja wouldn't start when clicking on the "Play" button from within the Steam client.

For context I'm running Steam on Fedora 19, 64 bits. I have a separate "Library" folder on another partition on which I install the games instead of Steam's default location in ~/.local/share.

Running the game from the command-line

Launching from the Steam client gives me zero information, just a brief black screen, so I thought I would see what happens when attempting to launch the game from the command-line.

jpichon@localhost:~/games/steam/SteamApps/common/mark_of_the_ninja/bin$ ./ 
dlopen failed trying to load:
/home/jpichon/.local/share/Steam/ubuntu12_32/steamclient.sowith error: cannot open shared object file: No such file or directory
[S_API FAIL] SteamAPI_Init() failed; Sys_LoadModule failed to load: /home/jpichon/.local/share/Steam/ubuntu12_32/
[S_API FAIL] SteamAPI_Init() failed; unable to locate a running instance of Steam, or a local steamclient.dll.
./ line 3:  6477 Segmentation fault      (core dumped) ./ninja-bin32

Note that the Steam client must be started in order to even get that far. That library does exist at that location, let's see what's preventing it from being loaded:

$ ldd /home/jpichon/.local/share/Steam/ubuntu12_32/ =>  (0xf77cb000) => not found => not found => /lib/ (0xf67f4000) => /lib/ (0xf66ba000) => /lib/ (0xf66a1000) => /lib/ (0xf664a000) => /lib/ (0xf65fa000) => /lib/ (0xf65aa000) => /lib/ (0xf647b000) => not found => not found => not found => not found => /lib/ (0xf6437000) => /lib/ (0xf6432000)

A number of these libraries already exist in Steam's ubuntu12_32 directory. Let's add it to our library path.

$ export LD_LIBRARY_PATH=/home/jpichon/.local/share/Steam/ubuntu12_32:/home/jpichon/.local/share/Steam/linux32
jpichon@localhost:~/games/steam/SteamApps/common/mark_of_the_ninja/bin$ ldd /home/jpichon/.local/share/Steam/ubuntu12_32/ =>  (0xf7749000) => /home/jpichon/.local/share/Steam/ubuntu12_32/ (0xf676b000) => /home/jpichon/.local/share/Steam/ubuntu12_32/ (0xf6727000)
    ... => not found => not found => not found => not found

Yup, that does seem to help. Let's add the rest:

$ export LD_LIBRARY_PATH=/home/jpichon/.local/share/Steam/ubuntu12_32:/home/jpichon/.local/share/Steam/linux32:
$ ldd /home/jpichon/.local/share/Steam/ubuntu12_32/ | grep not

Excellent! Let's see if the game can run from the CLI now:

$ ./ninja-bin32 
[S_API FAIL] SteamAPI_Init() failed; no appID found.
Either launch the game from Steam, or put the file steam_appid.txt containing the correct appID in your game folder.
Segmentation fault (core dumped)

How to find a Steam appID?

That one's easy to find a solution for. One can either look at the ID in the store URL as linked earlier or check out steamdb. Let's create a file with the correct ID in that directory and try again.

$ emacs -nw steam_appid.txt
jpichon@localhost:~/games/steam/SteamApps/common/mark_of_the_ninja/bin$ ./ninja-bin32 
Setting breakpad minidump AppID = 214560
Steam_SetMinidumpSteamID:  Caching Steam ID:  76561198074768941 [API loaded no]
ERROR: Missing required OpenGL extensions.
ERROR: Missing required OpenGL extensions.
ERROR: Missing required OpenGL extensions.
ERROR: Missing required OpenGL extensions.

Missing required OpenGL extensions

At first I thought that was it - my laptop simply wasn't powerful enough to play the game. But fear not, ArchLinux came to the rescue and thanks to them I learnt about the handy -enablelog flag for the game.

$ ./ninja-bin32 -enablelog
$ less ~/.klei/ninja/log/rendering.log 
[16:34.09] (4144580416) EXT_texture_compression_s3tc required

The solution is to install the libtxc_dxtn package (available in rpmfusion-free) and/or set force_s3tc_enable=true as an environment variable (discovered in a cached version of the developer's official forum, as it's currently showing blank pages for me).

I think I had to restart X to make sure the new library was picked up correctly, and then success!

Additional notes: The game still requires the Steam client to be running, and the Steam overlay won't work. However your Steam status will be correctly shown as in-game and the time, etc, should update correctly.

Starting the game from Steam

Unfortunately, starting the game from Steam still didn't work, and I also happen to quite like the overlay especially for games that don't react well to Alt-tabbing. I modified the script to add the new paths and environment variables, with no luck.

To help with troubleshooting: right-click on the game name then go to Properties, there is a "Set launch options" button. There we can add the friendly -enablelog flag discovered earlier. Trying and failing to launch the game again gives us some helpful logs in the same location as before in ~/.klei.

[17:25.42] (4144023360) Failed to CreateDevice
[17:25.42] (4144023360) KGraphics failed to initialize.

[17:25.42] (4144023360) EXT_texture_compression_s3tc required

Sadly, the same problem as before - it turns out is likely not used at all when launching from Steam so the extra environment variables are not being picked up.

If Steam isn't using, how can I find out what it is using and if I can change it?

In the end, installing libtxc_dxtn.i686 (in parallel to the .x86_64 version) resolved the problem. I'm not sure why the game insists on using 32 bits libraries when articles over the web make it clear it supports 64 bits, but either way that did the trick and the game now behaves correctly like any other Steam game.

I'm still somewhat unhappy about that last part because it was more guesswork than debugging, and I don't feel equipped to properly gather information next time a similar issue occurs. How can I know which binary / path / file Steam is trying to launch and with what flags?

Hopefully while I go on to continue my Steam journey, this will have been helpful to someone else. Happy gaming!

Bonus track: the game is sloooow

After all this, it turns out my laptop is indeed a bit underpowered to play this particular game. Deactivating blur, bloom and displacement in the options helped, and so did greatly lowering the resolution (windowed mode would help too but it became pretty much unreadable to me then, so I favoured the fullscreen 640x480 instead. Your tolerance levels may vary!)

Leave a comment

Train the Trainer course FETAC Level 6

Last week I participated in a 3 day-long "Train the Trainer" course at Hibernian College in Dublin. My goals were to get a better understanding of how to teach to adults and learn how to design and deliver effective training sessions, in order to improve my technical courses and workshops, and teach better. It's something I had wanted to do for a couple of years and I'm glad I finally jumped and did it! I found the course both very enjoyable and very useful.

Choosing the course

Originally I was waiting for Engineers Ireland to put their 5-day "Train the Trainer" course back on their CPD calendar but after contacting them, it turns out they are not planning on running it again in the short term.

Trawling the interwebs, there are a lot of training providers out there and it can be difficult to figure out which ones are legit (perhaps I was lucky!). I decided to go with a FETAC approved course even though I don't truly need the certification at this stage, because I figured if a course is approved to offer a government backed certification it'll be somewhat serious. After that, it was down to the luck of SEO and how helpful people were when I requested information. The Hibernian folks answered all my questions promptly and are lovely to deal with, both by email and face-to-face.

The course

The advantage of a 3-day course is that you don't need to take so much time off work. The disadvantage is that it is pretty intense! I would recommend having a couple of hours available in the evening for homework, particularly on day 2. The course I did was instructed by Maura O'Toole, who also happens to have some background in computing from early in her career which made for a few funny stories. Otherwise as a professional trainer with a couple decades of experience, she had a lot of anecdotes to illustrate her content and advice and make them memorable. I also liked that although we did go through all the FETAC material, she made sure to contrast it with how the real world works whenever relevant, based on her own knowledge and experience.

It must be a somewhat stressful course to teach because as you explain how to do things, people are analysing what you're doing and checking how it matches against what you are saying - and will call you out on any discrepancy!

The first day is the most intense, I think, which is probably just as well since people come in full of energy and expectations. I learnt a ton right from the icebreaker and icebreaker analysis - not only about training in general but also things I specifically want to try in my next course. That got me enthused for the day! By day 3 it was more difficult to keep the energy levels very high, despite the interest still being there.

The class size is kept small, which is actually a FETAC requirement (max 8 people) and makes for a nice environment, particularly as people need to get up and present quite regularly. The participants' backgrounds were quite varied and we all heard presentations about horticulture, clinical trials, powerboat exams, TV production, programming...


The assessment is in two parts: a "skills demonstration" video where you spend 10 minutes - exactly 10 minutes - showing off your mad training/presentation skills, and a ~2600 words written assignment showing how you would prepare, design and deliver (or have already) a particular training session, to return within 4 weeks of completing the course. You need a pass mark (40%) in each component to get the certificate.

The requirements for the video are such that it contradicts a lot of what is learnt during the course. You shouldn't really be interacting with your students on the video (it's about showing your skills) - and it would probably be quite fake anyway. It's important to stick closely to the time. It was strange to pretend to teach programming with slides.

I still did my best though, I couldn't help wanting to try and plant the idea of maybe learning programming, in the head of my fellow trainees :-) They kindly indulged me. No one was particularly fond of the camera and the atmosphere was really supportive during the day, no matter the number of retakes.

According to the instructor, we all passed the skills demonstration (yay!), although the videos still need to go to the external FETAC examiner to confirm the final grades.

It was strange for me to go from nothing to doing a graded presentation on camera within 3 days. I'm used to preparing and rehearsing and rererererehearsing a lot more than that. It's probably good to just get it out of the way quickly, though perfectionists who want to shoot for the highest grades (ahem) will find it weird. I thought it was good.

Material-wise I was able to reuse content from my previous courses so that was one less concern in terms of preparation, I only had to adapt a little. People who never taught or trained before maybe have a bit of a rougher time (then again if they're deeply knowledgeable on a topic, maybe not). Likewise if you're not comfortable with public speaking (as in, at the level of standing up and introducing yourself/talking shite with a handful of supportive people in the room, without having a panic attack) I would carefully consider whether to attend such a fast-paced course.

A few things I learnt

It's comforting when best practices are described and this happens to match how I've been doing things :-) (For instance my way of doing training evaluation is probably not too crap).

It dawned on me at some point during day 2 that what I was trying to fix - the ways my sessions are designed - is not my main problem. My main issue is that the objectives for my courses are not defined clearly - I kinda try to fit as much as I can without overwhelming within the time I have available. Working from the results I want (using the useful "Training Analysis Framework" I now possess!) would allow me to clarify exactly what I want to achieve, which will then help me organise and (re)arrange my sessions as needed, rather than follow the chronological order. As a very important bonus point, it will help me write course descriptions that are more specific and should help "weed out" the people that the course is not designed for (i.e. non-beginners). I am really happy about this, this is a big problem each time.

I also learnt what I thought was my "happy smiley presentation face" is actually "my serious face." Must calibrate better! :-)

There'll be a lot more once I got through my notes again, but the fact that I was trying to fix the wrong thing was a huge revelation and I'm really happy I figured this out. Sadly I got sick right after the course (better than being sick for the filming, I guess!) and I haven't had a chance to sort out the rest of my notes - or, er, start on the assignment.


I have a couple of weeks to complete the assessment. Hopefully I can get a big chunk of it done over the week-end, once the cold is gone. From what I understand, it is quite time-consuming and the instructor suggested doing it for a course we're actually planning on teaching so that the output is useful and usable, rather than a simple academic exercise. I plan to use my intro to programming course for this, except on a different timeline (I'll imagine it's taught over a couple of days rather than in the evening - and who knows, if I'm inspired I might just go and try teaching it in that format too!)

After that, I want to schedule the course and teach again in Tog. I "paused" teaching because I felt my course wasn't good enough and I wanted to overhaul it first. As with many "let's redo it from scratch!" projects, it's just meant I haven't taught in over a year now... So, time to fix this, and as I refamiliarise myself with the course first time around, the only major change I'll make will be to update the examples to Python 3. It's time!

Updated in May to add: I passed! :) Let's go and teach all the things!

Leave a comment

Testing in Horizon Unit testing for the Openstack Dashboard

Belatedly, here are the notes for the design session/tutorial I gave about testing in Horizon at the OpenStack Summit in Portland, back in April. The etherpad is available over there. Session description:

The main aspect: the Horizon unit tests can be quite complex for new contributors and people extending Horizon to wrap their head around. Mocking with mox, the django unit testing framework,the openstack specific parts of the testing framework, selenium, fixtures/test data handling, qunit...This session could work as a tutorial/tips and tricks on the different testing components. Common errors being thrown and how to debug them. If people could bring up their pain points, that would also be useful.

If there is time, it would be interesting to also address the issue from another angle and think on how to improve what we have, particularly on the Selenium front which has been quite unstable.

General structure

There are 3 main parts to Horizon testing (4 if you include the bits that come from the Python unit testing framework, but we won't get into it here. If you've done unit testing before, it's the usual set of assertions and scaffolding that come with any unit testing framework).

As an example to map to what this is all talking about, I recommend keeping InstancesTest.test_index in the background.

Django unit testing


At the moment Horizon is compatible with 1.4 onwards. The django documentation is excellent and I recommend having a look. Thanks to django we get a lot of goodies for free to help with testing a web application. Among other things:

  • A test client, which mimics a very simple browser (no Javascript) to do GET and POST requests, and built-in tooling to have interesting interactions with the responses.
  • A bunch of additional assertions, to check the HTML, templates, etc., all documented in the link above.

If you're familiar with django already, or while you're reading the django docs, there are a couple of things to watch out for:

  • Horizon does not use, and does not have a database
  • Horizon doesn't use fixtures either (actually it does, but they're very different since they're not done the django way - cf. no models)

Horizon unit testing


Helper classes:

There are some docs for testing in Horizon, which contain useful advice for writing good tests in general. A few sections only are specific to Horizon:

Now let's have a look at, where the TestCase classes we extend in Horizon tests are defined.

The setUp() and tearDown() methods do the housekeeping for mox/mocking so that we don't have to worry about it when writing tests. The aforementioned Horizon-specific assertions are also defined in this class. It extends the django TestCase class thus all of the django unit test goodness is available.

In general, this class is the best documentation available of what happens in the tests and how they are set up.

Openstack Dashboard unit testing


Test data:

Helper classes:

The Horizon tips and tricks mentioned earlier also apply, but there are no specific documentation page about the topic.

A quick overview of openstack_dashboard/ and the sections that matter to us in the context of unit testing:

  • APIs

The API directory is the only place that talks directly with the outside world, that is, the various openstack clients. This is why Horizon doesn't have a database, because it doesn't store any data itself.

  • Test Data

The test data is also stored in a single directory, and contains the fixtures, that are used to represent (mock) the data returned by the different clients.

  • Helper classes

Like in the "framework" part of Horizon, a file defines the TestCases we extend later in the unit tests. This is where a lot of the magic happens: the TestCase extends the Horizon TestCase helper class described earlier, loads the test data, sets up mox, creates a fake user to log in. There's also a couple of useful assertions defined that are used all over the place.

There are other TestCase classes in there, for tests that may require an Admin user, testing the APIs, or Selenium.

A quick look at the example

The flavours returned by self.flavors.list() come from the test data.

We'll look at the mocking stuff in the Tools section. The APIs being mocked all live in the API directory, so this is the only place that needs to be mocked.

self.client() is the default django client, reverse() and assertTemplateUsed() also come from django.

self.assertItemsEquals() is a Python assertion.



In Horizon, mocks are used a lot, everywhere or otherwise running the unit tests would require a fully set up, running Openstack environment.

I found mox a bit difficult to get used to. There's a specific terminology, that translates to a different set of steps than is common in other mocking tools like mock.

First you record. That's the part in the tests where you create the stubs (in a decorator in the example) and "record" what you expect will happen (that's the place in the example that says: "when api.nova.flavour_list() is called with these exact arguments as described, return self.flavors.list()").

Then you replay, with self.mox.ReplayAll() which will make sure the rest of the test will get the data it expects, that you just mocked.

Finally, the reverify step is done in the parent TestCase class' tearDown() function, which calls self.mox.VerifyAll() and ensures the functions recorded were all called, and in the order defined.

There are lots of catches in mox, it's quite strict. Order matters. By default it assumes the mocked function will only be called once and fails otherwise (that's a big one that can be difficult to track down). MultipleTimes() will save you if a function needs to be called more than a couple of times.

Stubbing can be done via a decorator (which is the favoured way going forward) or a StubOutWithMox function, which can still be found in places.

Mox errors can be confusing and I recommend reading the Horizon docs about understanding mox output, which have a couple of paragraphs explaining different errors that may be encountered, the dreaded Expected and Unexpected calls.


Helper classes:

We use Selenium for testing Javascript interactions. It's a bit heavyweight since it requires starting a browser, so Python unit tests are preferred when possible.

It's more stable now (thanks Kieran), so hopefully we can write a few more tests for the places where it's needed.

qUnit (briefly)

qUnit is used for some of the pure Javascript tests.

It's not used a lot in Horizon. The handmade fixtures take a lot of effort to make so maybe it's better to use Selenium in most cases.

Tips and tricks

  • See the Tips and tricks from the Horizon testing topic
  • Use pdb to check the environment status
  • Anything else? From the session:
    • Mock everything, and if it doesn't work mock it again.
    • Selenium tests: having a flag to turn off/on mocking? So we can run them as integration tests when needed and make sure we still match the correct APIs - cf. blueprint
    • Using Selenium tests as integration tests: build more tests (start a VM, ssh into it)


Unfortunately, the day was running late (and I was speaking at the very next session) therefore the discussion part didn't have time to happen.

I'm disappointed about that and would welcome people discussing their experience and pain points, particular from a newcomer's perspective.

Fortunately when it comes to discussing the Selenium issues, Kieran Spear had successfully fixed it right before the Summit :)

Leave a comment

Evolving Open-Source Night Open-Source Night - June

The monthly Open-Source night experiment continues. On Wednesday, June 19th we had the June edition of Open-Source Night. Rory gave us a slightly-longer-than-15-minutes talk on OpenStreetMap, and the kind of contributions the project welcomes (data data data, really!). I was the only one to volunteer for a lightning talk, in stark contrast with the last event where we had multiple ones both by people attending open-source night and network people who happened to be visiting the hackerspace at the time.

Rather than doing an on-topic talk about an open-source project, I did a meta-talk about Open-Source Night itself and different ways in which it could evolve.

I make no secret that I don't think open-source night works very well in its current format. My goal (and measure for success) is to help people actually get started contributing.

Note: if you were at my deep dive on contributing to open-source and planning on attending the next open-source night, please do come!! This all just means that I think there are things that can be improved :)

Reminder: The current format

We're currently meeting on the 3rd Wednesday of the month. The event usually starts with two 15 minutes talk, ideally one on the life of open-source (e.g. licences, version control, IRC, using the command-line...) and one on how to contribute to a specific project. Then there's a number of 5-minutes-long-or-less lightning talks where people can introduce the project they will be working on during the evening. Then people break into groups or independently work on an open-source project of their choice.

Or that's the idea anyway. The talks usually work well and are inspiring, though they tend to run overtime and then people have trouble sitting at a table and doing things.

The future

These are my thoughts and ideas as to where open-source night might go in the future. These are not plans. I would like to hear feedback from interested people - attendees, would-be attendees, other organisers and thoughtful passerbys.

Topics: General open-source vs Project-specific

I see value in both topics, but perhaps attendees and would-be attendees favour one or the other, both, or neither? I haven't really heard much on this, what people find most useful. I think the project specific talks at least are interesting for both newcomers and established contributors, to see how other projects do things.

I believe 15 minutes is a good amount of time to get an overview, get inspired and get ideas. And not get too bored if already familiar with the topic.

I could see the value and how efficient it would be to focus on one project for a full session and guide people through contributing to it. However I can also see how it could be offputting to people not particularly interested in the project (e.g. "I don't use that distro, why should I bother attending?"). Perhaps as separate, off-shoot events if people are interested in leading that kind of session (get in touch!).

Topics: All kind of contributions vs Focusing on code

At the moment, I try really hard to emphasise (and encourage speakers to do the same) all the kinds of contributions that can be made - and are well needed! - even though my own experience lies in code-based contributions. Maybe I should give up on being inclusive and focus on what I know best, rather than try to be all things to all people? Code-focused open-source events could go from learning to program to fixing a bug.

Initially I was hoping people would step up to talk and encourage people to join their area of interest (I think we have e.g. experienced open-source translators around...) but that hasn't happened.

This is actually a point where someone came up to me after the talk and said straight off they really liked the breadth of contributions demoed during the talks, in particular mentioning last month's talk by Guilherme on OpenMandriva that did a great job showing how someone can help, in a multitude of ways, even if they're not all that confident in their coding skills.

Format: More course-like?

A couple of days before the June OSS Night I was pointed to this article on a really, really interesting summer course on learning to program the open-source way. That's a really cool concept. Should we entertain the thought of doing something similar during open-source night? e.g. A session on learning how to use version control with exercises, very workshop like, one month, some other topic the next one, etc.?

Probably not, but something to consider as a separate course with a shorter timeline. A course with one session a month will lose people and have little momentum. Is this the kind of things people have an interest in learning?

Format: Doing vs Listening/Talking

My goal with this event is still to get people started contributing. I'm not interested in organising a monthly night of talks. Finding speakers is stressful. If the talks aren't followed by some contributing action, to me the event is failing and I'm not interested in continuing to organise it. There are plenty of events around Dublin already where people can meet, talk tech and shoot the breeze.

With regard to open-source related talks, I think that's already handled well by the ILUG folks, who are now keen to set them up regularly again under the new chairmanship :) And we can join forces if that's the most attractive part of the event to folks. If your main interest is in having a regular night of open-source talks, get in touch and I'll be happy to help you have this in Tog. I'd attend with pleasure anyway, I'm just not interested in organising it and go speaker-hunting every 3 weeks.

I still believe we can make something really cool happen by putting in the same room people experienced in open-source together with newcomers interested in contributing. So I'm not giving up yet!

There's of course also the timeframe issue: with or without talks, an evening of maybe 3 hours is not a lot of time to accomplish something. Maybe we could (also/instead?) have events on Saturdays? And/or week-end workshops, Friday eve to Sunday?

HOWEVER, in any case an evening is still enough time to accomplish something, get started, get the momentum going, get unblocked and finish your contribution later at the week-end, in your own time.

You: Why are you here anyway*? ;)

* Or why weren't you? :) I'm just as interested in the answer to that!

Are you interested in learning how to contribute? Interested in helping and mentoring newcomers? What were you hoping this evening would be about?

I then invited people to have a productive discussion with me about this should they wish to, somewhat contradicting my own doing vs talking rant :-)

Please feel free and welcome to continue the discussion in the comments or by email, I would love to pick more brains and exchange ideas about this.

Django challenge

To avoid the talk being entirely meta (and in case people didn't care that much about all the blah blah blah and more about the doing!), I issued a challenge to attendees as well: this evening, run the Django unit tests suite. If that's something you're set up for, it'll take 2 minutes. If you're familiar with the concept but don't have all the dependencies set up yet it'll take 20 minutes. If this is all new to you it might take 2 hours, but what you learn you'll be able to reuse when you start working on a project you care about in the future, and it means it'll take less long then.

One person took me up on it and it took them 10 minutes. This shows how possible it is to actually get the ball rolling during open-source night, get people to realise they're not that far away from a first contribution.

I feel I should give the disclaimer that since the last time I talked about how to contribute to Django, the Django folks added to their docs a tutorial on how to make your first contribution, which just makes the project that little bit more awesome (and this challenge, easier to solve!)

Next Open-Source Night: July

So next month. That'll be on the 17th of July. Are you interested in giving a talk? :)

If no one volunteers we'll have a session similar to the first event except with more lightning talks. Lightning talks don't have to be prepared, there's no need for slides or anything you don't fancy. It's as simple as chatting about what you plan on doing or would like to do during the evening, inviting others to join you if they'd like.

It can be like:

"Hello, I'm Chris, a contributor to AwesomeProject which is a project that does this and that and also that thing. At the moment we're looking for help in $area1, $area2, $area41, if you think that's cool and you'd like to help, I'll be sitting at that table over here, come and chat with me. Maybe I can help you find a good first task. Otherwise I'll be working on the defroglirnator for the project -- er if you have any experience in that area I'd love to chat to you too."

or maybe

"Hey, I'm J. Bloggs, I've been using Wordpress for a few years, I think it's an awesome project and I'd like to start giving back. Tonight my plan is to figure out the new contributor process - if you're interested too, we can do this together. Come and chat with me."

It doesn't matter if there is no existing contributor to the specific project in the room. Since there are people familiar with the way open-source projects and communities usually tick, they will be able to help you if you get stuck.

Ok, that's it! I'm hoping to also have the time to find a few good first tasks in a new project, maybe LibreOffice. If not, then we can figure it out together on the day :)

I'm very much looking forward to hearing your thoughts, suggestions and ideas about all this, and perhaps also see you on the 17th.

Leave a comment | 2 so far

git diff showing a weird output ^[[1;33m^[[mmmmh?!

I came back to an old project on another machine only to find that the git diff command did not behave as expected anymore:

^[[1;33mdiff --git a/myproject/myapp/ b/myproject/myapp/^[[m
^[[1;33mindex 0216829..d9e1637 100644^[[m
^[[1;33m--- a/myproject/myapp/^[[m
^[[1;33m+++ b/myproject/myapp/^[[m
^[[1;35m@@ -87,6 +87,12 @@^[[m ^[[mclass DoomDoomDoom(models.Model):^[[m

Instead of showing the colours defined in ~/.gitconfig, it was displaying escaped sequences in black and white, as well as a "(stdin)" prompt at the bottom of the page.

At first I thought it was a difftool issue but actually it relates to the pager, i.e. with either of these commands things works well:

$ git --no-pager diff # No paging
$ git diff --color | less -R # With paging

The default pager in git is supposed to be 'less'... Still, making sure it actually is fixed this for me:

$ git config --global core.pager 'less'

I'm still annoyed. Why was a different pager being used (and not showing in git config --list) and what tool was it?

Leave a comment | 2 so far

Open-Source Night #2: March 2013

On Wednesday the 20th, we had the 2nd edition of Open-Source Night in Tog. I think it went well. Once again there was about a dozen attendees, many of whom have never contributed to open-source before. A third of them were also in Tog for the first time. It might be too early to matter but there was also very little overlap with the audience from last time.


We started the evening with 2 talks, meant to be about 15 minutes long each. Mark started the evening telling us about open-source licences and the philosophy they encapsulate/were born from. Then I walked through how one would go about contributing to Django, basically clicking through the Django website and explaining different tasks the project needs help with, particularly for bug fixing contributions.

After this, we had 2 lightning talks that were meant to last 2 to 5 minutes, to give people a chance to talk about a project they contribute to and get people to join in. This time the talks were more about ideas, which is fine, but both also ran overtime, which is less cool. I'm not sure if either found additional contributors/would-be contributors out of it for the evening.


The second part of the evening, the part that should be hands-on, didn't go so well. After the talks (which lasted for 1h30 instead of 45mins) and a tour of the hackerspace for the new people, most continued chatting instead of sitting down and getting things done. This especially saddened me for the ones who had never contributed before. The goal of the event is to help newcomers get started contributing, when they have experienced people at hand to ask questions to.

Next time

I'm not sure how to improve this next time and help attendees get started actually doing stuff. Running overtime for the talks really hurt for the rest of the evening, which is already such a short time to accomplish something. An idea: after my talk I was asked "How long would it take for someone to start from nothing to being able to run the Django unit test suite?" and maybe this kind of well-defined, self-contained task would be good to help people get started. It's not a contribution yet, but it's a first, necessary step toward it (for code contributions in any case), and it could be fun to try and mix this with some sort of open badge.

Somewhat related announcement: open-source night won't happen on April 17th next month but probably on April 24th instead. Check the calendar for confirmation. If you're interested in speaking on a topic relating to the life of open-source or a project in particular, please get in touch :)

Leave a comment

Open-Source Night: Event #1 February 20th

On Wednesday, Tog hosted the first monthly Open-Source Night.

It's an event I'd been wanting to organise for a while, with an eye on it being hands-on and slanted toward helping interested people get started in open-source, but I wasn't sure what format would work best. I'm still not sure, but in the spirit of release early, release often, I thought I'd give it a shot for a few months and iterate.

For the first event, about a dozen people showed up. About 7-9 of them had already made some kind of contribution, most people had a clear idea of the project they wanted to contribute to for the evening, and 3 were hesitant and not sure what they wanted to do.

Blackboard with project names

We started with 2 super short talks, an ill-prepared one from myself about what to do tonight: basically find the contributor's guidelines for the project you're interested in and speak to the person next to you for help, since we had such a skewed ratio of experienced contributors. Triona followed with a talk on what she planned to do in the evening with Free Penguin, an open-source sewing pattern for Tux plushes. The maintainer hasn't updated nor responded to emails in years, so it seems it will need to be forked in order to start improving the documentation. Open-source projects aren't all about code! :)

I directed the hesitant project-less people toward Cheryl and the Dreamwidth project, which has an excellent reputation for being friendly to newcomers. Even without an experienced contributor around, I thought figuring things out together would be a fun learning experience. It may not have been that effective though, people were interested and looked around but nothing got accomplished (perhaps that is to be expected for a first couple of hours getting acquainted with a project and open-source?). Then further efforts were thwarted by technical problems (bugzilla down). Cheryl's thoughts abut this is that it's difficult to get into a project one doesn't feel strongly about (a similar downside applies to projects discovered via OpenHatch, as someone else mentioned to me).

There were a couple of serendipitous meetings, like the person wanting to get started with Debian packaging who happened to be sitting besides a Debian Developer.

But overall, I think having encouraged people to come along already having a project in mind made it difficult to form groups and encourage collaboration, because people ended up working on the project they had planned to alone. It may not have been a great experience, particularly for people who didn't know anyone or hadn't been in Tog before.

I also need to become more familiar with projects who have good, specific non-programming-related tasks for newcomers. I had a general idea but wasted time trying to find the details. We had a graphic designer interested in either contributing his design skills, translating or participating in testing efforts but I wasn't able to quickly find a good "Here's a concrete task you can do now" for some of the better known projects. He did discover InkScape and became eager to learn it, so I hope to see him again in Tog in a few weeks for teaching an intro workshop to InkScape :-) (Thanks Borud!!)

Ideas on how to evolve the format for next time:

Choose one project and make it the main focus of the evening, at least at the start. Meaning only one presentation, that is a bit longer (ideally 20 minutes, max 30 -- we still need time to actually do stuff!) and give specific, step-by-step instructions on "this is where you go to find something to work on, this is how you choose a task" and afterwards have the people interested in working on the project do so together - several people to one task can work, to encourage learning together and avoid getting stuck. People are still welcome to work on whatever else they want to of course. This was suggested by Ulrich based on the recent Debian Bug Squashing Parties he attended.

Becky said there was an interest in a GitHub pair programming type of exercise. People upload code on GitHub they never touch again. Working on someone else's code with the help of the author could turn into an instructive experience. It would also be cool to see what a pull request looks like from both sides.

I think we can try both these things for next time, the GitHub pair programming could start after the presentation for people not interested in working on the highlighted project.

Now. The next step is to find a project to highlight and a willing contributor who'd like to present and guide, for the next session on March 20th. Ideas, volunteers? :)

Feedback and general thoughts on evolving the format are warmly welcome as well.

Leave a comment

Talk transcript: Making your first open-source contribution

Slides available on SlideShare (I need to fix an embedding bug on the blog, oops).

Most of you know what Open Source Software is and hopefully think it's awesome. Have you ever contributed a patch? A translation? A bug report? Would you like to do any of this?

(If this is the first time you hear the term, roughly open-source is software for which the source code is freely available, that can be redistributed and modified.)

This talk is for people who like open-source and would like to give back, but are not sure where to start, or if they're smart enough or if their skills would be valued.

And my goal is to encourage you to make the jump from 0 to 1 contribution (or one more!) :)

Because I'm a software developer, this talk focuses a bit more on code contributions. (Don't think this means other types of contributions aren't needed, help is always welcome everywhere!) For many years, I wasn't strongly attached to any particular project but got patches in here and there (Sugar, Gnome, Django...) Nowadays you're more likely to find me in the land of OpenStack.

First, let's clarify something important: you don't need to be a genius to contribute. It's not as difficult as it may initially appear. All skill levels and all types of skills are needed and appreciated.

As to where to start, first I'm going to tell you about a wonderful shortcut, and then I'll go through how it usually works.

OpenHatch is an organisation whose mission statement is: "helping newcomers find their way into free software projects." They aim to bring together all the simple bugs, help requests and help wanted, documentation, all sorted by project and by language. It's a great way to get started.

Now, the way it usually works. When you're looking to contribute to a project, you should first look around for contributor guidelines. If a project has contributor guidelines, it's an excellent sign. It means that they care and that they've thought about it, which is very important when it comes to first contributions.

Read them! You don't have to remember it all. It will give you a sense of direction and an idea of what matters for the project, what to watch out for too (patch format, coding conventions, where/who to talk to, etc.)

As an example, here's a screenshot of the Gnome documentation for new contributors. There's a lot in there! They care a lot about welcoming new people.

In any case, whether a project has contributor guidelines or not, the workflow tends to be the same. Read the guidelines if they exist :) From then on, look at the bug tracker to find something that you'd be interested in working on. Now that you know which part of the project you will be working on, build it. Find the bug, fix it and submit your patch!

I'm going to be using the first contribution I made to Gnome as an example throughout this presentation. The Gnome folks are a very friendly community, and have a special tags for bugs that are good for newcomers called "gnome-love". In other projects this may be called "easy picking", "bite-sized", "low hanging fruit", etc... It should be mentioned in the contributor guidelines.

Look at the list of bugs tagged with that keyword and find one you like that is easy. (Avoid choosing a big feature as a first contribution. You need to earn some trust first, as well as pick up the project technical and cultural conventions.)

Once you know what you will be working on, it's time to build the software. This is very important, you will be learning new tools, perhaps even new languages. For instance I chose a bug from gnome-terminal which is written in C and uses autotools, which I wasn't very familiar with. This is why it's important to select a small first bug, because you have a lot more to learn to get there.

If you can't find instructions to build the software, you have a couple of solutions. Sometimes a mentor comes together with the "easy pickings" tag, or the community has its own mentorship program. You can also go back to the magical portal mentioned earlier, OpenHatch, where "training missions" are available to get people up to speed with some of tools commonly used in open-source.

People forget they had to learn all this in the first place. Don't sweat it. This is a stepping stone.

Once you have a working build, it's time to reproduce the bug, find it and fix it! If you're lucky, the location of the bug may have been mentioned in the bug report. As said earlier, the person who marked the bug as an easy task may be willing to help mentor you through it. It's ok to ask for help if you're having trouble.

As an example of a first task, I was lucky, and I indeed picked a very simple one - changing a colour in the gnome terminal!

Once your fix is ready and tested (you have rebuilt the software with your fix in it), it's time to submit the patch. Now is a good time to refer yourselves to the contributor guidelines once again, it will be useful to find out what your patch should look like (coding guidelines), what command you should use to create the patch, and where you should send it. If there are no such instructions, the safest path is to attach the patch to the bug report in the tracker.

And... congratulations! You've made your first contribution to open-source. Take the time to pat yourself in the back and be proud, you deserve it.

The process isn't quite finished yet: the next step is to wait. Perhaps your patch will be accepted since it's a small contribution. It's just as likely you might get some feedback on how to improve it - everybody wants to make their project better so don't take it personally, take the feedback on-board and resubmit the patch. If your patch gets lost in the ether, you should consider pinging the component or project maintainer.

In my case... I was lucky :) The patch was accepted and merged in the main codebase about an hour later!

If the only answer you get is silence - don't take it personally, really. People want you to stay, a healthy project know they need new people in order to stay alive. Open-source projects are always short in resources.

If the people involved in the project you contributed to have a bad attitude, don't be discouraged. And don't stick around either, there are a ton of cool, useful projects with friendly communities who could use your contributions. Life's too short.

If you've done your research, read the guidelines, there won't be any dragons. Most people are very nice! It's great to become part of a community that cares about creating the most awesome project they can.

And as a closing word before opening for questions: remember They are people dedicated to helping newcomers find their way.

Leave a comment | 5 so far

"Making your First Open-Source Contribution" Ireland Girl Geek Dinners

Hello good people who attended my talk on "making your first open-source contribution" for the January edition of the Girl Geek Dinners in Dublin. I hope you enjoyed it!

The slides are available on Slideshare - this version is actually missing a couple of recent updates, the main one being the mention of the Open-Source Night starting in Tog on Wednesday, February 20th. Come make your first contribution or help others get there!

If you're looking for a copy of the hand-out, you can download it here.

I'll be posting a transcript of the talk in the next couple of days. It still needs a bit of proof-reading :-)

Many thanks to Christina for organising GGD!

Picture of the talk
(Thanks to @Imisaninja for the picture)

Leave a comment

<~ Older posts