awesome — jd:/dev/blog

The bad practice in FOSS projects management

Thu, 09 Jun 2016 00:00:00 GMT

During the OpenStack summit a few weeks ago, I had the chance to talk to some people about my experience on running open source projects. It turns out that after hanging out in communities and contributing to many projects for years, I may be able to provide some hindsight and an external eye to many of those who are new to it.

There are plenty of resource explaining how to run an open source projects out there. Today, I would like to take a different angle and emphasize what you should not socially do in your projects. This list comes from various open source projects I encountered these past years. I'm going to go through some of the bad practice I've spotted, in a random order, illustrated by some concrete example.

Seeing contributors as an annoyance

When software developers and maintainers are busy, there's one thing they don't need: more work. To many people, the instinctive reactions to external contribution is: damn, more work. And actually, it is.

Therefore, some maintainers tend to avoid that surplus of work: they state they don't want contributions, or make contributors feel un-welcomed. This can take a lot of different forms, from ignoring them to being unpleasant. It indeed avoids the immediate need to deal with the work that has been added on the maintainer shoulders.

This is one of the biggest mistake and misconception of open source. If people are sending you more work, you should do whatever it takes to feel them welcome so they continue working with you. They might pretty soon become the guys doing the work you are doing instead of you. Think: retirement!

Let's take a look at my friend Gordon, who I saw starting as a Ceilometer contributor in 2013. He was doing great code reviews, but he was actually giving me more work by catching bugs in my patches and sending patches I had to review. Instead of being a bully so he would stop making me rework my code and reviews his patches, I requested that we trust him even more by adding him as a core reviewer. time contribution.

And if they don't do this one-time contribution, they won't make it two. They won't make any. Those projects may have just lost their new maintainers.

Letting people only do the grunt work

When new contributors arrive and want to contribute to a particular project, they may have very different motivation. Some of them are users, but some of them are just people looking to see how it is to contribute. Getting the thrill of contribution, as an exercise, or as a willingness to learn and start contributing back to the ecosystem they use.

The usual response from maintainers is to push people into doing grunt work. That means doing jobs that have no interest, little value, and probably no direct impact on the project.

Some people actually have no problem with it, some have. Some will feel offended to do low impact work, and some will love it as soon as you give them some sort of acknowledgment. Be aware of it, and be sure to high-five people doing it. That's the only way to keep them around.

Not valorizing small contributions

When the first patch that comes in from a new contributor is a typo fix, what developers think? That they don't care, that you're wasting their precious time with your small contribution. And nobody cares about bad English in the documentation, don't they?

This is wrong. See my first contributions to home-assistant and Postmodern: I fixed typos in the documentation.

I contributed to Org-mode for a few years. My first patch to orgmode was about fixing a docstring. Then, I sent 56 patches, fixing bugs and adding fancy features and also wrote a few external modules. To this day, I'm still #16 in the top-committer list of Org-mode who contains 390 contributors. So not that would call a small contributor. I am sure the community is glad they did not despise my documentation fix.

Setting the bar too high for new comers

When new contributors arrive, their knowledge about the project, its context, and the technologies can vary largely. One of the mistakes people often make is to ask contributors too complicated things that they cannot realize. That scares them away (many people are going to be shy or introvert) and they may just disappear, feeling too stupid to help.

Before making any comment, you should not have any assumption about their knowledge. That should avoid such situation. You also should be very delicate when assessing their skills, as some people might feel vexed if you underestimate them too much.

Once that level has been properly evaluated (a few exchanges should be enough), you need to mentor to the right degree your contributor so it can blossom. It takes time and experience to master this, and you may likely lose some of them in the process, but it's a path every maintainer has to take.

Mentoring is a very important aspect of welcoming new contributors to your project, whatever it is. Pretty sure that applies nicely outside free software too.

Requiring people to make sacrifices with their lives

This is an aspect that varies a lot depending on the project and context, but it's really important. As a free software project, where most people will contribute on their own good will and sometimes spare time, you must not require them to make big sacrifices. This won't work.

One of the worst implementation of that is requiring people to fly 5 000 kilometers to meet in some place to discuss the project. This puts contributors in an unfair position, based on their ability to leave their family for a week, take a plane/boat/car/train, rent an hotel, etc. This is not good, and everything should be avoided to require people to do that in order to participate and feel included in the project and blend in your community. Don't get me wrong: that does not me social activities should be prohibited, on the contrary. Just avoid excluding people when you discuss any project.

The same apply to any other form of discussion that makes it complicated for everyone to participate: IRC meetings (it's hard for some people to book an hour, especially depending on the timezone they live in), video-conference (especially using non-free software), etc.

Everything that requires people to basically interact with the project in a synchronous manner for a period of time will put constraints on them that can make them uncomfortable.

The best medium is still e-mail and asynchronous derivative (bug trackers, etc), as it is asynchronous and allow people to work at their own pace at their own time.

Not having an (implicit) CoC

Codes of conduct seem to be a trendy topic (and a touchy subject), as more and more communities are opening to a wilder audience than they used to be – which is great.

Actually, all communities have a code of conduct, being written with black ink or being carried in everyone's mind unconsciously. Its form is a matter of community size and culture.

Now, depending on the size of your community and how you feel comfortable applying it, you may want to have it composed in a document, e.g. like Debian did.

Having a code of conduct does not transform your whole project community magically into a bunch of carebears following its guidance. But it provides an interesting point you can refer to as soon as you need. It can help throwing it at some people, to indicate that their behavior is not welcome in the project, and somehow, ease their potential exclusion – even if nobody wants to go that far generally, and that's it's rarely that useful.

I don't think it's mandatory to have such a paper on smaller projects. But you have to keep in mind that the implicit code of conduct will be derived from your own behavior. The way your leader(s) will communicate with others will set the entire social mood of the project. Do not underestimate that.

When we started the Ceilometer project, we implicitly followed the OpenStack Code of Conduct before it even existed, and probably set the bar a little higher. Being nice, welcoming and open-minded, we achieved a descent score of diversity, having up to 25% of our core team being women – way above the current ratio in OpenStack and most open source projects!

Making people not English native feeling like outsider

It's quite important to be aware of that the vast majority of free software project out there are using English as the common language of communication. It makes a lot of sense: it's a commonly spoken language, and it seems to do the job correctly.

But a large part of the hackers out there are not native English speakers. Many are not able to speak English fluently. That means the rate at which they can communicate and run a conversation might be very low, which can make some people frustrated, especially native English speaker.

The principal demonstration of this phenomena can be seen in social events (e.g. conferences) where people are debating. It can be very hard for people to explain their thoughts in English and to communicate properly at a decent rate, making the conversation and the transmission of ideas slow. The worst thing that one can see in this context is an English native speaker cutting people off and ignoring them, just because they are talking too slowly. I do understand that it can be frustrating, but the problem here is not the non-native English speaking, it's the medium being used that does not make your fellow on the same level of everyone by moving the conversation orally.

To a lesser extent, the same applies to IRC meetings, which are by relatively synchronous. Completely asynchronous media do not have this flaw, that's why they should also be preferred in my opinion.

No vision, no delegation

Two of the most commonly encountered mistakes in open source projects: seeing the maintainer struggling with the growth of its project while having people trying to help.

Indeed, when the flow of contributor starts coming in, adding new features, asking for feedback and directions, some maintainers choke and don't know how to respond. That ends up frustrating contributors, which therefore may simply vanish.

It's important to have a vision for your project and communicate it. Make it clear for contributors what you want or don't want in your project. Transferring that in a clear (and non-aggressive, please) manner, is a good way of lowering the friction between contributors. They'll pretty soon know if they want to join your ship or not, and what to expect. So be a good captain.

If they chose to work with you and contribute, you should start trusting them as soon as you can and delegate some of your responsibilities. This can be anything that you used to do: review patches targeting some subsystem, fixing bugs, writing docs. Let people own an entire part of the project so they feel responsible and care about it as much as you do. Doing the opposite, which is being a control-freak, is the best shot at staying alone with your open source software.

And no project is going to grow and be successful that way.

In 2009, when Uli Schlachter sent his first patch to awesome, this was more work for me. I had to review this patch, and I was already pretty busy designing the new versions of awesome and doing my day job! Uli's work was not perfect, and I had to fix it myself. More work. And what did I do? A few minutes later, I replied to him with a clear plan of what he should do and what I thought about his work.

In response, Uli sent patches and improved the project. Do you know what Uli does today? He manages the awesome window manager project since 2010 instead of me. I managed to transmit my vision, delegate, and then retired!

Non-recognition of contributions

People contribute in different ways, and it's not always code. There's a lot of things around a free software projects: documentation, bug triage, user support, user experience design, communication, translation…

It took a while for example to Debian to recognize that their translators could have the status of Debian Developer. OpenStack is working in the same direction by trying to recognize non-technical contributions.

As soon as your project starts attributing badges to some people and creating classes of different members in the community, you should be very careful that you don't forget anyone. That's the easiest road to losing contributors along the road.

Don't forget to be thankful

This whole list has been inspired by many years of open source hacking and free software contributions. Everyone's experience and feeling might be different, or malpractice may have been seen under different forms. Let me know and if there's any other point that you encountered and blocked you to contribute to open source projects!

FOSDEM 2016, recap

Sat, 06 Feb 2016 00:00:00 GMT

Last week-end, I was in Brussels, Belgium for the FOSDEM, one of the greatest open source developer conference. I was not sure to go there this year (I already skipped it in 2015), but it turned out I was requested to do a talk in the shared Lua & GNU Guile devroom.

As a long time Lua user and developer, and a follower of GNU Guile for several years, the organizer asked me to run a talk that would be a link between the two languages.

I've entitled my talk "How awesome ended up with Lua and not Guile" and gave it to a room full of interested users of the awesome window manager 🙂.

We continued with a panel discussion entitled "The future of small languages Experience of Lua and Guile" composed of Andy Wingo, Christopher Webber, Ludovic Courtès, Etiene Dalcol, Hisham Muhammaad and myself. It was a pretty interesting discussion, where both language shared their views on the state of their languages.

It was a bit awkward to talk about Lua & Guile whereas most of my knowledge was years old, but it turns out many things didn't change. I hope I was able to provide interesting hindsight to both community. Finally, it was a pretty interesting FOSDEM to me, and it was a long time I didn't give talk here, so I really enjoyed it. See you next year!

Ten years as a Debian developer

Fri, 24 Feb 2012 00:00:00 GMT

Ten years ago, I joined the Debian project as a developer.

At that time, I was 18 and in my first year at university, hanging out with the TuxFamily system administrators, which included 3 french Debian developers (sjg, igenibel and creis).

I was learning Debian packaging while working on VHFFS, and decided to package one or two non-yet-packaged software for Debian. My friends pushed me into the NM process, and less than 2 months later I was a Debian developer. One have to admit that back in the days, the NM process was really fast if you were able to reply to the questions quickly. :-) I think I became the youngest developer among Debian's ones.

That was my first steps in a Free Software project, and it was really exciting.

In 10 years, I've been doing a lot of different things for Debian. Sure, I've been using it all the years long, but let's recap a bit what I did, from what I recall.

My first Debian only project was apt-build around 2003, and later rebuildd in 2007.

I built the Xen packaging team in 2005, I've been a Stable Release Manager for a year in 2006, and did heavy bug squashing to release Etch that same year.

I also was an Application Manager in 2006 and managed the application of 2
Debian developers (Jose Parrella and Damián Viano).

I admit I've been less active in Debian after 2007, mainly because I was busy working on awesome, GNU Emacs and others software.

Since 2011, I joined the OpenStack packaging team and I'm working on OpenStack on a (almost) daily basis.

I don't know how many packages I touched, managed or updated, but that should be one or two hundreds. I still maintain 53 of them.

After all, the adventure has been really pleasant, and I had the chance to work with and meet fabulous and smart people. I always liked this project and what it's trying to do.

After all these years, I'm definitively staying! See you in another 10 years, folks! :)

Various news: what happend during summer

Tue, 22 Sep 2009 00:00:00 GMT

It's been a while since I blogged about something. So here's a bunch of things I've done the last month.

Holidays

Well, I've been in holidays one week. :-P

awesome

There have been a huge number of changes between 3.3 (released in June) and 3.4 (almost relesed). I wrote a small but very useful object layer on top of Lua, which adds a class/object system a bit like gobject. I've also replaced all the hooks by per-class/object signals. Finally, the awesome Lua basement are cleaner than they were before, and the extendability is improved. How nice.

We're trying to release 3.4 (rc2 should be out soon), but the development pace is a bit slower than a year before. We're basically almost 2 months late on what was our previous release rate. Not a big deal however.

I've started working on 3.5 slowly. It gonna get amazing new features too. :-)

Google Summer Of Code 2009

I've mentored Mariusz Ceier on XCB GSoC. He worked on adding Xinput2 and XKB extensions. And he managed to do this. His work should be imported ASAP, the discussion has started on XCB maling list last week.

In exchange, Google offered me (and to every mentor) an awful blue t-shirt! Thanks Google! :-P

Taking the other direction

Wed, 15 Apr 2009 00:00:00 GMT

I've started to develop awesome more than 18 months ago, and somehow I feel it's time to stop a bit and think where we come from and where we are going to.

The motivation

I never though I'd be written a window manager one day. That seems kinda stupid when you see how many window manager there's around.

As many people, I've tested and have been using tons of window manager: Window Maker, Fluxbox, etc.

In August 2007, I was using fvwm since 2004 and was quite happy with it. I used the famous fvwm crystal as a configuration starter and then rewrote lots of stuff. Digging into ''fvwm'' configuration files was boring, and since I'm lazy, I never really configured it to fit entirely my needs.

The thing is that, in July 2007, my workstation died. I bought a new one based on the amd64 architecture. Too bad, with this new box, fvwm decided that it will not longer runs and was segfaulting almost every time I logged in.

I was really upset. Another failure in the window manager world. So I decided to get the yearly ride of testing many window managers. I went on the no more developed stuff like the *boxes, ion3, etc… but well, I did not like them, there were not powerful enough, too bugged or upstream was insane.

Then I found xmonad. The Haskell configuration file format made my cry. I did not want to learn Haskell, it seemed too obfuscated to me. At that time it was even not packaged for Debian, so I gave up. But I found

The jdwm

I just added a 'j' in front of dwm and started to hack it days and nights to add many feature I missed, like multi-head, etc… On 5th September 2007, I created a git repository to host my code.

That's gonna be… awesome.

Five days later, on 10th September, I finally found a name for my new pet: awesome, borrowed from Barney Stinson who heavily uses and abuses this word.

The 1.x branch

The first releases until December were noted 1.x. It was just a better dwm with a simple flat configuration file.. The configuration file used libconfig, but it was a very poor choice. And I was not able to put in into Debian because of name clash.

The 2.x branch

The 2.x branch came in January 2008 with a brand new configuration file format based on libconfuse, which was a bit more powerful. Many concepts and features that have been added in this branch are still used in the current 3.x branch.

At this time, between December 2007 and April 2008, the community was growing smoothly.

But as I said, awesome 2 was based on a flat configuration file. That raised a problem very soon: users expectation were growing and the development team (me and a couple of regular contributors) was unable to cope with them.

One of the event that started to change my mind was the support for titlebars.

When I've added titlebar support, it was minimal. It was on top of a window, with the window title. Dot. Then I've started to add a lot of options, like the application icon drawing, the position (left, right, bottom) etc.

And then users started to ask for more, like: "add titlebar on windows only when the window is floating".

That's ok, but that's complicated: that's again another option to do some stuff conditionally. And then, why don't add titlebar on windows when ?

The 3.x branch

Why

At that time, around April 2008, I'd totally stopped development. I was trying to find a solution which was simple and powerful. But after 2 weeks of thinking, I was not able to find anything else than: use a real language for configuration.

So, I've started prototyping awesome 3 using Lua. The choice was not obvious, and despite the problem Lua might suffer, it's one of the easiest language to integrate into an existing application.

But, let's go a little back: in January 2008, Arnaud Fontaine contacted me because he was interested to use awesome as one of its school project. He decided to port awesome from Xlib to XCB, a modern asynchronous X library.

His work took some time, but in May 2008, Arnaud did finished to port git master version of awesome to use XCB.

Consequently, I decided to start a new major branch, using XCB instead of Xlib (no change for users in this regard) and Lua instead of our previous flat configuration file format.

Development

It took me a while to get from here to there, but in September 2008, it was ready. We had a simple Lua API, and the XCB port was working perfectly.

It took us some time to release and have something totally working, because we had to work on XCB and contribute back to the project. It was really not ready to use by an application, but we did great work in this area and it's now really fine.

We're still here

Releases continue to happens, 3.1 around December 2008, and 3.2 around March 2009. 3.3 should be here in June.

One of the drawback we had, is that we moved many stuff from C to Lua. Why? Because writing things in Lua is quicker and easier to maintain than C, and makes thing more configurable for the user.

For example, the layout algorithm used to organize window were written in C until 3.2 came out. At that time, users had no choice than using a set of predefined layout to organize their windows.

Starting with 3.2, if they have minimal knowledge about geometry, they can start writing a layout function organising windows on the screen.

But this kind of API changes was a bit rough for users, since they had to port some part of their configuration file to the new API. The thing is that the project was still a teenager at that time, not really knowing were it will go. But I'm happy to announce that API breakage are more and more rare (so far only one minor between 3.2 and 3.3), and anyway always for the Good.

But I admit that it built a bad reputation around awesome 3.x during its first month of existence.

Future direction

I am currently working on 3.3 development. We have still many things to do. Time passing, we get more idea, and more users. And more users bring more ideas. We also have many more contributors, and some guys are even taking maintainer-ship of some code area.

Conclusion

My post title is "Taking the other direction" because I feel this way.

I've got that feeling that some approaches in projects like GNOME are sometimes bad. Please don't misread me, I know we are not playing in the same yard.

When adding a key shortcut for starting an application makes you dig into gconf, I wonder how this is a win for the user.

Well, it's probably a win for the end-user, but I surely am not one of them. And I don't intend to target them with my software, anyway.

And now, when I hear things like GNOME 3.0 and the "desktop shell" approach, that makes me smile. Guys, it was time, but have luck. What I see from here, is that any desktop control interface is wrong somehow, and that there's no approach that can fulfill all users wishes.

I think that we, the awesome development team (no pun intended) took the direction of building a frame-work window manager rather than a solution written in marble.

We (partially) solved the issue of UI ergonomic by not writing one and allowing the user to write his own. I don't say that's easy to do for most of users, but it's doable.

And I think it's worth it: I use window managers since I use Linux, around 1998. If something like ''awesome'' came 5 years ago, I'd be using it so far, because you can write Fluxbox or WindowMaker using awesome in a hundred of Lua code. And you can write your own version of it. And it starts in less than 3 seconds, supporting almost all standard desktop specification (ICCCM, EWMH, XDG, system tray, message notification, D-Bus, etc), whereas many of the window mangers do not.

You can even write and play space invaders.

Finally, I'm happy about the the road we took so far, and hope we will continue into that direction. The rants I read about our project are not that big, compared to the kudos we received.

OpenOffice is better as a pager than as a text processor

Wed, 11 Feb 2009 00:00:00 GMT

Since several month, awesome users have reported a bug with OpenOffice.org. When using OOo and clicking on a menu, or using the mouse wheel to read a document, the currently selected tag (desktop) will change automagically to another one.

I've digged into awesome and found that awesome received a _NET_CURRENT_DESKTOP request. As defined by EWMH,
this kind of request are sent by a pager to change the active desktop.

That was weird. Nobody is using a pager here. So, I just kicked my gdb out, attached it to OOo, breaking on XSendEvent call. And I got it:

Breakpoint 1, XSendEvent (dpy=0x1a00080, w=483, propagate=0, event_mask=1572864, event=0x7fff1fd70d70)
   at ../../src/SendEvent.c:46
(gdb) bt
#0  XSendEvent (dpy=0x1a00080, w=483, propagate=0, event_mask=1572864, event=0x7fff1fd70d70)
   at ../../src/SendEvent.c:46
#1  0x00007f8c0ab4193f in vcl_sal::WMAdaptor::switchToWorkArea ()
  from /usr/lib/openoffice/basis3.0/program/libvclplug_genlx.so
#2  0x00007f8c0aafdbd8 in X11SalFrame::Show ()
  from /usr/lib/openoffice/basis3.0/program/libvclplug_genlx.so
#3  0x00007f8c1378623c in Window::Show ()
  from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#4  0x00007f8c13785f40 in Window::Show ()
  from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#5  0x00007f8c1372cb54 in FloatingWindow::StartPopupMode ()
  from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#6  0x00007f8c1373c877 in ?? () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#7  0x00007f8c1373ccf2 in ?? () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#8  0x00007f8c1373ce84 in ?? () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#9  0x00007f8c13795e7f in ?? () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#10 0x00007f8c13797e74 in ?? () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#11 0x00007f8c13796748 in ?? () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#12 0x00007f8c0aafe6f8 in X11SalFrame::HandleMouseEvent ()
  from /usr/lib/openoffice/basis3.0/program/libvclplug_genlx.so
#13 0x00007f8c0ab040c2 in X11SalFrame::Dispatch ()
  from /usr/lib/openoffice/basis3.0/program/libvclplug_genlx.so
#14 0x00007f8c0ab31625 in SalX11Display::Yield ()
  from /usr/lib/openoffice/basis3.0/program/libvclplug_genlx.so
#15 0x00007f8c0ab356f3 in ?? () from /usr/lib/openoffice/basis3.0/program/libvclplug_genlx.so
#16 0x00007f8c0ab2df1f in SalXLib::Yield () from /usr/lib/openoffice/basis3.0/program/libvclplug_genlx.so
#17 0x00007f8c135b050e in Application::Yield ()
  from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#18 0x00007f8c135b0587 in Application::Execute ()
  from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#19 0x00007f8c17517e80 in ?? () from /usr/lib/openoffice/program/../basis-link/program/libsofficeapp.so
#20 0x00007f8c135b4b24 in ?? () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#21 0x00007f8c135b4bc5 in SVMain () from /usr/lib/openoffice/program/../basis-link/program/libvcllx.so
#22 0x00007f8c1754ca6c in soffice_main ()
  from /usr/lib/openoffice/program/../basis-link/program/libsofficeapp.so
#23 0x000000000040105b in main ()

I started digging more into the code, and this is what I finally found in salframe.cxx:

        // #i45160# switch to desktop where a dialog with parent will appear
        if( mpParent && mpParent->m_nWorkArea != m_nWorkArea )
            GetDisplay()->getWMAdaptor()->switchToWorkArea(mpParent->m_nWorkArea );

Beautiful! It even has a comment with a IssueZilla bug number. Let's go and see where it comes from.

After 10 minutes of research to find that fucking IZ, I finally found the link to the issue #45160. The bug is IMHO not related to OOo but to a window manager doing poor job.

I've found that an awesome user already reported an bug… err, wait, I mean an issue as issue #96684 (remember there's no bug in OOo, only issues) and I commented about it.

It seems OOo developers have agreed to fix that bug eventually.