Contributing Documentation

Contributing Code

First Steps

Exherbo uses git for source code management (SCM) and its code is maintained on our Gitlab instance.

Workflow for contributing to package repositories

This is directly lifted from the work of Ciaran McCreesh and can be found in its original form on his blog. This will be updated to match changes there as possible.

Repositories are configured as normal, with their sync set to point to the usual remote location. The location is specified in /etc/paludis/repositories/<repo>.conf like this:

sync = git+https://git.exherbo.org/<repo>.git

To contribute on a repository, first fork it and pull a local clone. Fork these repositories on our Gitlab instance to easily push your contributions. In the following explanation we will use arbor, but it works with any repository.

Now that we have a local clone of the fork in /home/users/ciaranm/repos/arbor, change /etc/paludis/repositories/arbor.conf to:

    sync = git://git.exherbo.org/arbor.git local: git+file:///home/users/ciaranm/repos/arbor

Normally, when you sync, you’ll be syncing against upstream. To sync with the local clone:

    cave sync -s local arbor

The workflow now is: - Update the local copy of your personal repository to be in sync with upstream. It possibly saves you from rebasing your work on changes that happened in the meantime. Or even worse, somebody might already have done the exact same thing. - Work locally on your changes until everything works. The package should resolve fine on your system. - Use the wonders of git rebase -i to tidy up your work into nice friendly pushable commits.

Some things to note:

Style requirements

Submitting patches for package repositories

Submitting your repository for inclusion in unavailable-unofficial

If you have your own repository and its quality is fairly high, you should submit it for review so it will be included in unavailable-unofficial. To do that, just add it to our infra-scripts git repository as in this example and push it to Gitlab.

This way, others will not duplicate any work you may have done, and you will get helpful tips on how to improve your packaging skills. Also, this will allow others to more easily contribute to your packages or point out bugs. See kloeri’s blog post if you are not yet convinced.

We expect a decent level of responsiveness from you and we reserve the right to remove repositories with broken packages if you do not respond to patches and inquiries within a reasonable amount of time (Rule of thumb: within 30 days).

More concretely, if there’s a patch for your repository for 30 days or more, we will consider your repository for removal from unavailable-unofficial. You’ll get up to two additonal “wake-up calls” before the actual removal, though. If you’re not on IRC, we’ll send you an email to your last known address (so make sure to use a valid, working email address in your exheres, etc.).

This is not about “punishing” you or something like that but to ensure that the repositories in unavailable-unofficial are maintained according to Exherbo’s quality standards.

Remember that it is trivial to have your repository re-added once it is fixed up/maintained properly again.

Exherbo hook

To have fancy IRC commit notifications, please consider using our push hook. We currently support GitHub, Gitorious and self-hosted repositories. Ask any Exherbo developer on IRC to get the WebHook URL.

Notes

Some of the guidelines outlined in this document are based upon Documentation/SubmittingPatches, as part of git


Copyright 2009 Ingmar Vanhassel Copyright 2013 Ciaran McCreesh, A Frederick Christensen