The OpenHatch blog is graciously powered by WordPress.
Entries (RSS) and Comments (RSS).

Infrequently Asked Questions: Bloomington

by Shauna October 29th, 2013

At each Open Source Comes to Campus event, participants ask unique, thought-provoking questions. We decided to write down these questions and answer them more fully on our blog. If you have any additional suggestions or advice, please add them in the comments!

These questions are from our IU Bloomington event. This post was co-written with Asheesh Laroia, with contributions by Karen Rustad and Máirín Duffy.

Read on to learn more about building open source communities, diff and patch, open source design, and part-open/part-closed projects.

I’m worried that I’ll be a burden on a project because I’m so new. What kind of effort does a project have to make to build an open source community?

First of all, you should know that expert open source community builders like Linus Torvalds understand this tension between training new contributors and the time it takes from existing maintainers to mentor them. I’ll quote two paragraphs from a 2004 post Linus made on the Linux kernel list:

On Tue, 21 Dec 2004, Jesper Juhl wrote:

> Should I just stop attemting to make these trivial cleanups/fixes/whatever
> patches? are they more noice than gain? am I being a pain to more skilled
> people on lkml or can you all live with my, sometimes quite ignorant,
> patches?
> I do try to learn from the feedback I get, and I like to think that my
> patches are gradually getting a bit better, but if I’m more of a bother
> than a help I might as well stop.

[Linus replied:]

To me, the biggest thing with small patches is not necessarily the patch
itself. I think that much more important than the patch is the fact that
people get used to the notion that they can change the kernel – not just
on an intellectual level (“I understand that the GPL means that I have the
right to change my kernel”), but on a more practical level (“Hey, I did that small change”).

Another thing to keep in mind that is, for most projects, the project leader is the only contributor (source). Consider this — the act of “bugging” them with questions as a newcomer can make them more enthusiastic about the project as a whole!

If it were trivial to build an easily accessible open source community, virtually all projects would do it. There is some effort involved. Of course, a lot of the work which makes a project welcoming to newcomers – good documentation and setup guides, a well-maintained issue tracker, active development, standards of conduct in the community – makes the project better for everybody. But it does take time and energy, which many projects aren’t willing to expend. That’s why we exist! We know that some projects put more effort into welcoming contributors, and we want to help you find those projects.

The kinds of projects that welcome newcomers don’t see you as a burden. They see you as a huge help – even when you’re struggling to understand bugs in the issue tracker or get the development environment set up. When you ask a member of an open source project for help, that gives them important information about what part of their project is confusing or incorrect. The questions you ask and guidance you need lets them know how help others later on. And of course, once you’ve gotten familiar with the project, you’ll be able to help even more. The right kinds of project see that potential in you and want to work with you to get there.

Two rules of thumb for people who worry about being too much of a bother (which includes us, sometimes!): First, if people on the mailing list or the bug tracker haven’t told you to stop talking, then you’re probably okay, even if they haven’t replied to you yet. Second, if you want another opinion, just join the #openhatch IRC channel and ask us.

Students looking at something

What are the flags for the patch and diff commands?  Why would you want to use them?

The quick answer is, “You always want diff -u, and you usually want patch -p1.”

The long answer is: The diff tool generates a text file summarizing the changes between some files. There a variety of formats that diff knows how to generate, and the default is an older format that isn’t widely used anymore. The most commonly used change format is “unified diff,” which is what “-u” specifies. My favorite (in its weirdness) is the “Ed script” format; you can read about that on Wikipedia.

As for patch, the most common command line flag to change is the number after “-p”. This helps patch choose which files on your computer to edit. Recall that the idea of diff+patch is that one person creates a file using the diff tool, and another person applies it on their computer with patch. In that case, what if the person creating the diff had placed the files in a different directory than you? Your use of the “-p” parameter controls that, and the “Levels in the Patch Command” section in How to create and use a patch in Linux explains more. Not everyone is excited about having to choose the right option; you can read Dustin Kirkland’s blog post where he wrote a tool to avoid having to ever pass this parameter in!

Like most UNIXy utilities, diff and patch have pages in the “manual”, which you can access by running man diff or man patch in your terminal. You can also read these online, for example at man.he.net.

Two students looking at a laptop

How can I help open source projects with design?  Would I look in the bug tracker?

answer written by Máirín Duffy and Karen Rustad

You rarely find purely-design issues in bug trackers. Often you find a feature request which has an obvious design component, but the design and the development are lumped together in the same ticket. One approach, then, would be to make a new ticket for just the design, link it to the original ticket, and then assign that to yourself, which both communicates your intent and breaks the feature request up into more manageable chunks of work. But you may be better off looking specifically for projects that have design teams, as sometimes the design teams have ticket trackers with easy tickets designers can pick off, or a specific process for getting started as a designer.

It’s important to note the difference between a visual designer/artist and a UX designer/usability practitioner. Visual designers/artists usually find it easier to get involved – most projects need icons, logos, marketing materials or other artwork at some point. I [Karen] have had the best success just asking a project maintainer in IRC what design needs they have, or pointing out a design problem I’ve noticed and expressing an interest in fixing it, and chatting from there.

It’s harder to get involved as a UX designer or usability practitioner. Design is ‘controversial.’ (See the GNOME 3 design.) You always want the developers to have your back so it’s very important to cultivate a great relationship with them and be very willing to move on to another project if a project you’re interested in turns out not to be so interested in having a UX designer or usability person involved. The best luck I [Máirín] have had getting involved cold turkey, when I had no experience with the project or people involved, was to actually design something for them first, send it to them, and ask for feedback. If you get it wrong but it’s obvious from the work that you’ve got good chops then very likely they’ll start a healthy dialogue with you and bring you into the fold; but the risk is you never hear back and the work you put in doesn’t really go anywhere (into the upstream you intended it for at least).

Student talking

What if you want to make only part of a project open source?

There are many reasons you might want to keep some parts of a project private.  Maybe your project deals with sensitive information and you currently store that private data alongside your code.  Maybe you’re a teacher and you don’t want students getting access to materials they’ll be tested on. Maybe you’re a company and financial success means waiting to make all of your work open source.  Maybe you’d like to wait until your work is more polished before you show it to the world (though this is a common trap that leads people to forget to ever share!).

Whatever your reason, generally the best way to proceed is to separate the open and private parts of the project into different repositories. There are several hosts that support both open and private repositories.  Some, such as Bitbucket, provide private repos for free (although only for five users or less), while others such as Github charge for them (although Github is currently providing private repositories for free to women through the Ada Initiative, and also a standing offer for students).  If the sensitive information is relatively limited, you may be able to keep it in a single file or folder outside of the version controlled repository where it is easily referenced.

If you need to keep information private for legal reasons, it’s important that you consult with whoever put those rules into place to make sure your chosen solution adequately protects the information.

You can read more about a part-open, part-closed strategy from people who have done it. “Open Source (Almost) Everything” is a seminal post on the topic, by Tom Preston-Warner, one of the founders of GitHub; you can also read posts decrying this “open core” model.

Students working on laptops

Write a comment