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:

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:

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:

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.

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:

Any help you can give here is most welcome.

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.