Participating in Obnam development

The Obnam project is quite small, as far as software projects go. There is one main developer, plus a few others who sometimes help out. It would be nice to have more people involved, and this chapter is an introduction for that.

It is a common misunderstanding that only code matters in a software project. On the contrary, without a number of other things, code is useless, particularly so in a free software project, including Obnam. Examples of necessary things in almost any serious software project:

• writing and updating documentation, which includes manuals and websites
• translating documentation, and the software's user interface
• providing support to users with questions or problems
• reporting actionable bugs
• processing bug reports: asking for clarifications, reproducing the reported problem, finding the cause of the problem, and developing a suitable fix
• porting the software to various platforms, including different operating systems, different versions of said operating systems, different versions of the languages and libraries the software uses, different hardware, etc
• quality assurance: developing and performing manual and automated tests and benchmarks, and analysing results
• hosting and operating web sites, mailing lists, IRC channels, other communication channels
• handling project governance, which includes dealing with conflicts between people
• managing the project in general, including making sure things don't stall
• finally, writing the code itself, which is a necessary, but not sufficient part of having a project that people other than the developers can use it

This list is insufficient; additions are welcome. See the rest of this chapter for suggestions on how to contribute to the list.

Helping support users

Perhaps the easiest way to participate in the project is to help support other users of the software. This is easy, and doesn't necessarily require more than being able to use the software oneself. Yet it is quite valuable, as it frees others from doing that. Even with the highest quality, easiest to use software, there's always some need for user support:

• Code can be wrong, and a user may experience this. Analysing the situation and isolating the bug is an important part of the software development process.

• Documentation can be wrong, or out of date, or written in anticipation of a feature that doesn't exist yet.

• Some people have misunderstandings, due to whatever reason, which leads them to have problems when using the software. Figuring out what the actual problem and its cause are can be a time consuming process, but often does not require any special skills, except for patience and a willingness to ask a lot of questions.

In the Obnam project, the best way to help out with this is to subscribe to the obnam-support@obnam.org mailing list or join the #obnam (irc.oftc.net) IRC channel, and start answering questions.

It's OK to not be an expert. Helping others is a great way to learn. If you make it clear you're not an expert, but are trying to help anyway, usually makes others appreciate your help even more.

Some suggestions on doing support work:

• Try to understand what the person needing help is actually trying to achieve, rather than answering their literal question. Better yet, do both.

• You don't need to have the solution to respond. A quick, but incomplete answer that nevertheless moves the discussion forward is helpful. Even if you don't know the correct answer, it's good to ask a question that results in the person needing help providing more information, or finding the solution themselves, or inspires someone else to discover the solution,

• Always be helpful and polite. Never respond with things such as "read the fine manual" (or RTFM for short). It's OK to say that the answer is in the manual, but then provide a link, and possibly also a quote.

• People who need help are often frustrated, and sometimes desperate, because they've tried and tried to solve the problem on their own, but have failed. This can leak through their messages. Ignore it, unless they actually become impolite, at which point its probably best to escalate the situation. Avoid getting into a quarrel about who's right or who said what and what did they mean by it.

• It's better to not respond at all, than respond while irritated, annoyed, or angry. It's more important for the project to maintain a polite and helpful atmosphere in the long run than to solve any current technical problem.

In short, if you do your best to be polite, friendly, and helpful, go ahead and respond.

Writing and updating documentation

The project has various kinds of documentation.

• The obnam.org website.
• The manual page.
• The manual (which is what you're reading now).
• Various blog posts around the web.

Writing documentation is fairly easy. Updating it takes a bit more effort, since it requires reviewing existing documentation to make sure it's up to date. The main goals of Obnam documentation are:

• Accuracy.
• Clarity.
• Completeness.
• A bit of dry humour in places.

Any help you can give here is most welcome.

• Read through existing documentation.
• If you find anything that's wrong, inaccurate, incomplete, missing, or unclear, send a note to the developer mailing list.
• If you can include a new wording, all the better. It's not required.
• If you can provide an actual patch, perfect, since it makes it easiest to incorporate your suggestion. Again, it's not required.

You don't need to be a good writer. As part of the process, others will review what you send, and will point out anything they feel can be improved. For example, suppose you notice that a paragraph in this manual is unclear, but you don't know what it actually should say. If you send a mail saying this, others can then come up with a better wording.

Translating documentation

The Obnam manual and manual page are written in English, and have been translated to German. More languages are most welcome.

The author of this manual is not particularly familiar with the process of translation, and so wishes someone else would fill in this section.

The Obnam user interface is not currently translatable, and making it so will require code changes. Helping make those code changes would be nice.

Developing the code

Assuming you already know how to program, it's fairly straightforward to work on the Obnam code base. At least it's meant to be so: if you have trouble, please ask and point out what's unclear or wrong.

Check out the source from the git server, and read the README file for details on how to get started, and how to run the automated test suite, and how to send patches. See the website for some development documentation, including explanations of the on-disk data structures.

Code changes that are not very trivial should be sent in a form that can be handled by git. This can be actual patches sent to the mailing list, or a URL from which changes can be merged.

Project governance

The Obnam project has a very informal form of governance: the founder of the project, Lars Wirzenius, has all the power, and everyone else has no power. As the project grows, this will change.

If there's a social problem somewhere, for example someone is misbehaving, it's best to report it to Lars directly. If Lars is the problem, it's best to call him out directly.