The Obnam project welcomes contributions. If you want to help Obnam become better, you can. There are many ways to contribute that don't involve writing code.

• improve the documentation
  • fix typos or grammar
  • clarify some part
  • provide a helpful diagram
  • write missing parts of the documentation
• improve the website
  • fix typos or grammar
  • fix a layout problem
  • suggest a helpful link
• try out the software and report your back your experiences
  • what went well? what could be improved?
• help others who have trouble with the software
  • on the fediverse, IRC, Matrix, the issue tracker or wherever
• help the developers understand what you need
  • document your use case
  • help formulate acceptance criteria
  • become a formal stakeholder
• fix a bug
• add a missing feature

We co-ordinate our work primarily via the Radicle issue tracker. Using it requires using Radicle. If that's a problem for you, please get in touch and we may be able to arrange something. THe important thing is to communicate and co-ordinate, not the channel via which that happens.

Set up to change the web site

To contribute a change to the web site, you set up like this:

• Clonethe [web site repostiory][].
  • you can clone it without Radicle, but you'll need Radicle to create a patch
• Make a new git branch and start making changes.
• Commit everything.
• Either create a Radicle patch (git push rad HEAD:refs/patches), or submit the changes in some other way to the project, such as via email.

You can, if you want to, test your changes by building a local copy of the website, but that's not required.

Set up to change the code

If you want to make a contribution by changing the code, you can set up an environment following these steps:

• Install the Rust language toolchain, using rustup or another way.
• Install any other build dependencies, as described in the README and [debian/control] files.
• Clone the code repository.
• Run make to make sure everything works.
• Make a new git branch and start making changes.
  • make sure make works with your changes
• Commit everything.
• Either create a Radicle patch (git push rad HEAD:refs/patches), or submit the changes in some other way to the project, such as via email.

Getting Obnam to change so you can do what you want to do

Sometimes it happens you want Obnam to do something that it doesn't quite know how to do. Here's some advice for that situation.

• For any substantial discussions, we prefer the issue tracker over chat systems. Chat systems are great for quick questions, but they're also ephemeral and only help the people who happen to be present at the time. The issue tracker lasts longer, and allows long-form replies and taking time to respond in depth.

• When suggesting or contributing a new feature, please always start by explaining the thing you want to achieve. "I want to back up a a historic computer's disk with a file system that isn't supported by Linux" is a better start than sending a patch for backing up raw disks. It's easier to judge a change fairly if the need for it is clear.

• If you contribute a functional change, please also change the automated test suite to verify the changed functionality changes. If you're not sure how to do that, please ask, and we'll help. We rely on our test suite to be able to make large changes rapidly and confidently. (Adding tests for bugs, when they're fixed, would be nice too, but we don't insist on that.)

Some caveats so you know what to expect:

• Obnam is a hobby project. It might take a while for us to respond. Please be patient. However, if you open an issue, and haven't heard back in a week, ping us on the issue or via a chat system. We try to be prompt, but sometimes work and life get in the way of working on hobby projects.

Code review process

We use Radicle for code hosting, with a manually updated mirror on gitlab.com. We prefer Radicle patches for tracking changes and reviewing them, but if that's troublesome, GitLab or whatever works for you is OK too.

Changes are currently reviewed by Lars, the founder of the project, and he is also the only one who can merge. This will change as the project grows. Processes will also evolve with growth.