Ebuild policies

If you have write access to the overlay and want to modify the overlay please obey the rules below. If you don't have write access yet, but want to contribute in more than just random patches, please join our IRC channel and ask for write permissions. The most important rule is the rule of sanity. Always keep in mind that other people use the overlay differently! It's often better to keep two versions of a ebuild than breaking random things or force users to update their whole system. This is especially true for critical system components like gcc, glibc or similar.

ALWAYS TEST!

Before submitting any patch, modification or proposal please check the following points:

  1. Make sure you don't break your host or any other architecture.
  2. Wrap cross-compile patches with 
    if tc-is-cross-compiler; then
  epatch <your first patch>
  epatch <your second patch>
  ...
  epatch <your Nth patch>
fi
  3. Apply patches to automake/autoconf instead of configure.
  4. Avoid to use the ${ROOT} variable in src_* as it is assumed to be bad practice by Gentoo devs.
  5. Use eclass functions (e.g. for getting the compiler of cross-compile checks) instead of reinventing the wheel!
  6. Test your stuff, both on HOST and TARGET!
  7. If you take patches from elsewhere, please give credit to the original author!

Add ebuilds

If you found a bug and have a patch for this bug, you probably want to add it to our overlay. If you don't have write permissions, the best way is to submit a new ticket. Read more on the Found bugs? page. If the ebuild is not yet in our overlay do the following:

  1. Make sure you base you patch on the latest version of the package.
  2. Update your portage tree.
  3. Syncronize your ebuild to the latest version in portage and minimize the differences.
  4. Cleanup the ebuild you want to submit!
  5. Make sure you have all patches and files needed by the ebuild.
  6. If you modified the ebuild in the last steps, redo the testing above!
  7. Upload the ebuild and all files required. Please add a descriptive commit message!!!
  8. Make sure you unmasked the version you've just uploading in the corresponding keywords.
  9. Scan the open tickets and close the once you fixed with a reference to the commit.

Modify an existing ebuild

Sometimes patches in the overlay can be improved or additional bugs can be fixes by adding patches. Please, please, please with sugar on top, test your stuff! There are a few points to consider while modifying an ebuild in the overlay:

  1. Don't break existing fixes!
  2. Give a short description in the ebuild why the patch is needed. This helps during the process of submitting stuff upstream.
  3. Check if the current version of the overlay ebuild is still in sync with the portage tree. Try to port over fixes done there. Consider a version bump if a newer ebuild can be found upstream. Don't forget to unmask the bumped ebuild!
  4. Testing, testing, testing!
  5. Commit your changes to the overlay after each fixed issue. Add a descriptive commit message!!!
  6. Scan the open tickets and close the once you fixed with a reference to the commit.

Delete ebuilds and keywords

It's a good thing to keep the overlay as small as possible to reduce the maintenance overhead. There are the following situation for deleting keywords and ebuilds:

  1. Delete a keyword file if the version specified in the file is outdated or marked stable in the ebuild.
  2. Delete an ebuild if a fixed version can be found upstream. Remember to unmask the upstream version.
  3. Delete an ebuild if you bumped the version in the overlay. Remember to unmask the newer version of the ebuild.

To not break things for others (especially users of stable ebuilds) the following rules apply:

  1. Make sure there is a working version of the ebuild either upstream or in the overlay.
  2. The newer version should not block other packages nor force newer version of other packages. It's better to have two versions of the ebuild than to force users to update random packages.
  3. Check that all fixes of the overlay version are in the upstream version.
  4. Ensure that this fixed version is unmasked for users of stable ebuilds!