The ChangeLog must be updated with each commit. The echangelog tool should be used to create ChangeLog entries; the format of a ChangeLog is now defined as "whatever echangelog creates".

You should include references to any relevant bugs. The standard format for doing this is via the phrase bug #20600 — this format (with the hash sign included) is recognised via and similar tools. When including user-submitted ebuilds or patches, you should credit the user with their full name and email address (or whatever they use to identify themselves on bugzilla — some users prefer to be known only by a nickname).

If you are changing keywords, make sure you clearly state what keywords you add or remove. "Marked stable" is a nuisance for architecture teams, even if there was only one keyword in the ebuild at the time. "Stable on all archs" isn't generally any better (and should you really be stabling on all archs?) — do you mean "all", or "all the ones that are currently keyworded"? A list like "x86 sparc mips" is much more useful.

A typical ChangeLog snippet might look like the following:

    *vim-6.3.068 (25 Mar 2005)

      25 Mar 2005; Ciaran McCreesh <> +vim-6.3.068.ebuild:
      New release. Fixes bug #79981, bug #81289, bug #83383, bug #83416, bug
      #83565, bug #85758, upstream patches up to 6.3.068.

      22 Mar 2005; Aron Griffis <> vim-6.3-r4.ebuild:
      Stable on alpha

Writing correct ChangeLog messages

Your message should explain what specifically you changed and, if relevant, why. You don't need to write an essay or even a complete sentence (ChangeLog messages, however, are required to be in 'proper' English so no fixed that bug kthx Bob messages — please do use punctuation), so long as it is easily understandable and (preferably) greppable. Bad and good examples, all of which are based upon real messages: