Whenever you update (or write a new) an ebuild, you must also update its (or create a new) ChangeLog. The skel.ChangeLog contains a sample ChangeLog that you can use as a basis.

The purpose of the ChangeLog is to document what is being done, why it is being done, and by whom. This allows both developers and users to trace the changes made in an easy way.

The ChangeLog is primarily targeted at users, so be sure to keep your writing short, to the point, and avoid getting verbose about the internal technical details.

In order to be able to test your ebuilds and let Portage know about them, you must place those in a known directory. Portage will use the PORTDIR_OVERLAY variable which you can define in /etc/make.conf. You should set this variable to your directory (e.g. /usr/local/portage).

In that directory, you must use the same structure (and categories) as in /usr/portage.

Using this PORTDIR_OVERLAY, your ebuilds remain on your system, even after an emerge sync, and they are still known to Portage.

Have a think about how you will test whether this package works. Sometimes the developers have already included a make test or make check routine that will test the basic functionality of the package. If so, then running FEATURES=test ebuild foo-x.y.z.ebuild test will execute it. If it is broken try to fix it so that it works (and submit the patch to the upstream developers).

If this is not the case consider adding a src_test routine to your ebuild. This is executed before the src_install routine and can be very helpful for testing the program works across various architectures. The architecture developers will appreciate if you add a routine here so that they do not require knowledge of the package's functionality.

Please keep in mind the general requirements of an ebuild here. The src_test routine must not be interactive. If the test routine depends on other packages use the test USE flag to specify the optional compile time DEPENDancies. Also, please note that src_test routines are not recommended for graphical X applications as the user running portage often cannot run them successfully.

We have a few useful tools to help you with writing and maintaining your ebuilds.