Contributing

Overview

Exherbo uses git for source code management (SCM). Some of the guidelines outlined in this document are based upon Documentation/SubmittingPatches, as part of git.git

Submitting patches for package repositories

• When submitting a new package, first consider whether it’s really important enough to be in the official repositories, or whether you should instead put it in your own supplemental repository. If the quality of your supplemental repository is reasonably high, host it somewhere, and we’ll consider adding it to the unavailable-unofficial repository.

• Do submit original work. Don’t blindly copy ebuilds, adjusting for differences between ebuilds and exhereses. If you need to install a package, there is a tool far more suitable that you can use instead of blindly adapting ebuilds to exheres.

• Don’t try to bump large and critical packages (e.g gcc, X, grub…) on your own without speaking to their maintainers. Bumping such packages takes some time and requires extra testing, so please be patient.

• Sometimes patching upstream sources is unavoidable. If you do apply patches, make sure they’re properly documented according to our patches policy, found in exheres-for-smarties. Always consider that adding patches that will not be accepted upstream means you get to maintain those.

• To be included in any of our repositories, contributions must be licenced under the GPL-2. Add an appropriate copyright notice if your contributions to a given file warrant it. See exheres-for-smarties.

• Patches can be contributed via our bugzilla, or in our IRC channel #exherbo. Committing patches in the IRC channel is favoured, the procedure is described in Using the patchbot.

Submitting patches for documentation and the website

• All our documentation is written in markdown format and uses Maruku for HTML conversion.

• We use the Creative Commons Attribution Share Alike 3.0 license for all documentation and website content. Contributions using other licenses are unlikely to be accepted.

• Patches can be contributed via our bugzilla, or in our IRC channel #exherbo.

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 it, just queue the url of your repository to unavailable-unofficial using the patchbot,e.g.: !pq git://foo.bar/foo.git ::unavailable-unofficial. 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.

Setting up your repository to report commits with CIA.vc

It is recommended to use CIA.vc to report commits from your own repository to #exherbo so that others can easily see any activity. This makes it easier for others to catch errors or make suggestions as soon as a change is committed rather than when it becomes a problem.

Setting up a post-receive hook in your remote repository

Depending on what service you use to host your repository, there are several methods of doing this.

GitHub

With GitHub, enabling CIA.vc reporting is simply a matter of checking the Active box for CIA in the Service Hooks in the Admin panel for your repository.

However, GitHub does not allow you to configure the project name sent to CIA, so instead, you can create a new project in CIA.vc for your repository.

The steps to setting up a new CIA.vc project are pretty straightforward.

1. Register an account at CIA.vc if you have not already done so.
2. Add a new project through the Your Account panel using your repository’s name as the project short name.
3. Fill out the relevant information in your project’s Metadata section.

After you have created your project, add your project to the list of projects to report in the #exherbo channel.

1. In the Your Account panel, go to the Bots section and add a bot to the #exherbo channel in the Freenode network.
2. Add your project at the end of the Filter by project box.
3. Hit save, then test it out by pushing a commit to your repository.

Gitorious

Gitorious currently does not allow you to add hooks to your repositories, so for now you can set up a CIA repository locally which you can configure the same as below. This way, when you push to this repository, your commits will be reported as usual.

A remote repository in which you can manually set up git hooks

Add a post-receive hook to your remote repository to send commit notifications to CIA.vc. To do this, you should save ciabot.bash to the hooks directory in your repository and configure it as needed.

Next, add a post receive hook similar to the one below to the hooks directory in your git repository.

#!/bin/bash

while read oldrev newrev refname ; do
    refname=${refname#refs/heads/}
    for merged in $(git rev-list --reverse ${newrev} ^${oldrev}) ; do
        bash hooks/ciabot.bash ${refname} ${merged}
    done
done

Now, when you push to this repository, commits should be reported to #exherbo.

Style requirements

• Configure your git author name and email properly. Use your real name. See man git-config, look for user.name and user.email.

• Generate your patches using git format-patch, from local commits. If your patch renames files, please use the options -M -C to git format-patch, to detect copies and renames. This makes the resulting patch much easier to read. Alternatively, you can enable -M -C by default by running git config --global diff.renames copy. See man git-format-patch.

• Use a clear and descriptive commit message, explaining the change.

  • Write a short one line summary, followed by an empty line, and, as you see fit, a more elaborate description of your changes

  • Version bump is not an acceptable commit message. You should at least mention the package and version you’re adding. Try running git log --oneline on a repository full of Version bump commits and you’ll understand why.

  • In case your making non-obvious changes, consider explaining the reasoning behind the changes.

  • Do make references to relevant bug reports, mailing lists, … where appropriate.

• Exhereses use 4 spaces and strictly no tabs for indentation. Run your patch through git diff --check, to verify that it doesn’t introduce whitespace errors.

• app-vim/exheres-syntax and app-emacs/exheres-mode will highlight common exheres syntax errors. Use them.

Caveats

• When testing documentation updates you should use the Makefiles in the git repository to generate the HTML. This makes sure you get the same results as on our servers. Make sure you have Maruku installed.

Copyright 2009 Ingmar Vanhassel

This work is licensed under the Creative Commons Attribution Share Alike 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/; or, (b) send a letter to Creative Commons, 171 2nd Street, Suite 300, San Francisco, California, 94105, USA.