This Time Self-Hosted
dark mode light mode Search

Motivating users and teaching them good practises

I’m quite sure that some of the possible voices stirred by my previous posts, and about my less-than-happy comments on Sunrise, is that I dislike or look down on user contributions. All the opposite, I actually think that user contributions are the heart and blood of Gentoo. But I have some particular views about them.

One of the most common approaches for user contributions in Gentoo when I joined was never to do the work in place of the users: get them to fix their ebuild, point out what needs to be worked on, and leave to them to submit an updated ebuild. I shared this sentiment for a while, but nowadays I don’t think it’s the best approach. Since, as I already expressed, there is no good documentation for Gentoo development, it’s difficult for the users to provide good ebuilds by themselves. And sincerely, there is too much old cruft in the tree that shows just a bunch of bad examples.

This works only to a point: those most interested in the inner workings on Gentoo might pick up the opportunity to improve their ebuilds; many others might just feel turned down and will stop caring about their ebuilds; or about Gentoo as a whole! This post by Stephan Gallagher points at something similar.

Now, most of us will agree on the point that the situation where the user stop caring about the ebuild, or decide to keep it in his or her overlay is not good for Gentoo as a whole, but there are two approaches on how to solve this. The one that I openly dislike, and attack, and is followed by the one developer I kept criticising, is to take the ebuild, even though “suboptimal” and commit it to the tree as the user contributed it. I think it is easy to see how that can be a problem.

My favourite approach, instead, is to fix the ebuild; try it out, get it polished, if needed contact upstream to fix possible issues… it might take extra work, even for something you don’t use or care much about, but it gets results handy. To take an example from the past months: Pavel contacted me about gearmand and drizzle; while I’m using neither and I wouldn’t have had time nor interest to write ebuilds for them out of thin air, I gave him a few pointers, and he got back to me with updated ebuilds; they weren’t perfect but they were a good starting point. I polished the ebuilds a bit further, sent upstream a few patches, and now Pavel is still maintaining them, and they seem quite fit for the job to me.

Saying that Pavel’s original ebuilds weren’t fit for the tree, and weren’t good enough, is not the same as insulting Pavel; I’m quite sure he agrees that they weren’t perfect; I’m also quite sure that his next ebuilds “out of thin air” will be better than them, since he has been able to see how some of the things were to be done. Something that, lacking a good documentation, is impossible for users to do without developers’ help.

Sometimes, it’s also easier to go upstream and fix some of the troublesome build systems before going on further with the ebuild, as Enrico will probably remember from the Gource work. But again, you shouldn’t be confusing showing users (and other developers, or developers from other projects) how to do the right thing, and criticising them.

*The perfect is the enemy of the done.*

Comments 8
  1. For the record (being the Pavel that Diego is writing about) – I wholeheartedly agree with what Diego wrote.Gearman and Drizzle are primarily server oriented packages that should always set the highest standard for ebuilds possible-breaking stuff on a cluster of servers is a kind of oops that can cost a lot of money.The ebuilds (esp. for drizzle) are still not perfect and I have have still lots of things to learn… Diego’s been sofar the best mentor I could imagine, he dosen’t mind answering stupid questions and helping out himself with issues that I’m unfamiliar with (pam or build system related issues).I’ve already been addressed earlier by two other users to help them get in touch with devs and start proxy maintaining a package. So should anyone else think my experiences could be useful feel free to get in touch using gentoo at killua-eu.

  2. I completly agree with both Diego and Pavel (and yes i’m the Enrico mentioned in the post).Diego was (and actually still is) very kind explaining me how to make ebuilds in the right way (and also a lot more than just that), and i was (and i’m still) very happy to learn from him and i enjoy trying to contribute to gentoo for what i can.That’s why i would be very sad if Diego will leave gentoo. Stay here Diego and keep fighting for your ideas! 🙂 And thank you very much for all your help

  3. Having committed once or twice to sunrise, and with a few ebuilds sitting in bugzilla dreaming of one day getting committed to the main tree, I have stand firmly behind the Sunrise QA procedure.My first ebuild (version bumping a pretty terrible ebuild) worked, but not well and not how it should. Following some gentle (and not so gentle) reminders, linkages, and a torturous first fix-post-fix cycle, I eventually passed QA and earned myself a Sunrise account. My next ebuild, just as you say in this article was _much_ better. My most recent got about three comments, but I could justify what was ugly/bad for each of them. One of these days, I’ll be able to write one from scratch that garners no gentle tut-tutting. Code review is a vital stage in any programming, and ebuild QA is analogous in many ways.While the docs aren’t perfect, they’re good _enough_ to get someone started – actually, I feel that the main problem is that there are a pile of legacy docs banging around on, which should have a large *WARNING: DON’T USE* at the top, with a link to the “Dev Guide”:… . Case in point, the “Ebuild howto”:… – it shares the same goal as the Dev Guide, but with less information, in a more confusing style, and out of date in places. It should be deprecated. It took me quite some time to find the Dev Guide when I started writing ebuilds – and I’m glad that I did!

  4. Flameeyes I think it would a shame to see you go. As a Gentoo user for a number of years I’ve seen it move in different directions, and I think you’re on the right track with the QA discussions. Gentoo can be bleeding edge (with the instability that can go with it) and a stable flexible distro. Keep at it; smacking devs who commit code without proper consultation or thought.I’ve been considering getting into Gentoo dev work but have found the state of documentation hurting the cause for getting new devs onboard; similar in thinking to Jim. Can you comment on that Flameeyes?

  5. Maybe you could use a classroom like the education project of does?…Basically one experienced dev talks about a specific topic on IRC so newcomers may learn from it. The IRC-Log is later published on the Wiki for reference.Another idea:Create an “improvement branch” in your VCS of the portage tree. Update “rotten ebuilds” there to be conforming to the newest coding standards (maybe while discussing the case in IRC/in a classroom). This would have two advantages:- If the ebuild gets versionbumped, the improvements can be merged into the main tree, cleaning up the portage tree without unneeded updates.- Newcomers might investigate the changes made in the improvement branch and learn about the dos and donts without being distracted by changes simply made out of necessity (or downright evil hacks).And if IRC, Wiki and a branch are not enough there is:…Which would allow to integrate all of the above …BR,Sweetshark

  6. Not about ebuilds, but I wrote a proposed FAQ on performing a major Gentoo Upgrade and a set of HOW-TOs for Gentoo. You can start here:…I would very much appreciate your input if you have the time.Also, I’m brushuing up on my bash scripting skills with the idea of perhaps taking on some ebuilds. To that end, I’m looking at the following links:…Are there other resources I should be aware of?

  7. I would consider #gentoo-dev-help to be a good place to get ebuilds reviewed as well as #gentoo-sunrise (if you’re planning to commit to sunrise, which is a good experiencel).Remember that if your ebuild is related to a particular gentoo project such as python, ruby, and especially java, the IRC channels dedicated to those projects will likely be helpfull in reviewing ebuilds.I don’t understand how sunrise is harmful; perhaps I am forgetful.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.