<section id="commit-messages">
  <title>Writing commit messages</title>
  <para>
    Following rules apply to writing commit messages in PLD CVS repository.
    They are mainly in charge in SPECS and SOURCES modules, but most of
    them should be used also in other modules.
    <orderedlist>
      <listitem>
        <para>
          <emphasis>
            Always supply a meaningful commit message
          </emphasis>
        </para>
        <para>
          Remember: your commit message will be logged and saved in the
          spec file as well as sent to the commit-list. Lines in commit
          message should be wrapped before 80th column. Examples of valid
          messages are:
          <itemizedlist>
            <listitem>
              <para>
                <literal>
                  "- spec adapterized"
                </literal>
              </para>
            </listitem>
            <listitem>
              <para>
                <literal>
                  "- added working Source0 URL"
                </literal>
              </para>
            </listitem>
            <listitem>
              <para>
                <literal>
                  "- completed docs"
                </literal>
              </para>
            </listitem>
          </itemizedlist>
        </para>
        <para>
          Examples of bad messages:
          <itemizedlist>
            <listitem>
              <para>
                <literal>
                  "i'm bored today"
                </literal>
              </para>
            </listitem>
            <listitem>
              <para>
                <literal>
                  ""
                </literal>
              </para>
            </listitem>
          </itemizedlist>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>
            Add a '- ' to your log messages
          </emphasis>
        </para>
        <para>
          ...so that the changelog looks nicer. Compare:

<screen>
Revision 1.4  1999/11/01 23:54:47  corleone
- added static subpackage with statically linked zsh,
- added BuildRequires rules,
- added info and DESTDIR patches.
</screen>

          to:

<screen>
Revision 1.2  1999/09/04 15:17:23  corleone
Updated to 3.1.6
Added more macros
Small fixes
</screen>

         </para>
         <para>
           Remember: a dash with a space after it. Something like this 
           looks ugly:

<screen>
Revision 1.4  2002/04/22 10:19:27  corleone
- pl fixes

Revision 1.3  2002/04/21 17:39:49  corleone
-add pl description
</screen>
        </para>
        <para>
          Try to be consistent.
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>
            Never correct mistakes in the logs
          </emphasis>
        </para>
        <para>
          Unless:
          <orderedlist>
            <listitem>
              <para>
                it's your own log message
              </para>
            </listitem>
            <listitem>
              <para>
                you want to correct a missing '-' at the beginning of a line
              </para>
            </listitem>
            <listitem>
              <para>
                you want to remove unnecessary empty lines
              </para>
            </listitem>
          </orderedlist>
          But don't commit cosmetic changes in changelogs as the only 
          changes in spec.
        </para>
      </listitem>
      <listitem>
        <para>
          Commit message like <literal>"- increased release"</literal>
          or <literal>"- release++"</literal> are wrong. You should always
          write number to which release was increased. This is because
          it should be clear for person reading just the changelog 
          what changes was made between particular releases.
          Similarly for version numbers (<literal>"- updated to latest 
          version"</literal> isn't very good commit message).
        </para>
      </listitem>
      <listitem>
        <para>
          Commit message like <literal>"- sources for foobar"</literal>
          when committing <filename>SOURCES/foobar-0.1.2.tar.gz</filename>
          also isn't very good idea.
          There are just two right messages for commits in SOURCES
          module regarding tarballs:
          <orderedlist>
            <listitem>
              <para>
                output of <command>md5sum</command>, like:
<screen>
9b65a7c19ef31a5dbc2f30627d1c3222  gcc-20020415.tar.gz
</screen>
              </para>
            </listitem>
            <listitem>
              <para>
                text: <literal>"- outdated"</literal>
              </para>
            </listitem>
          </orderedlist>
        </para>
      </listitem>
      <listitem>
        <para>
          Another bad idea is commit message with output of 
          <command>md5sum</command> when
          committing patches or, heaven forbid, spec files. In case
          of patches you should mention:
          <orderedlist>
            <listitem>
              <para>
                source (author and/or url) of patch (unless it is yourself, 
                this is assumed default)
              </para>
            </listitem>
            <listitem>
              <para>
                what patch fixes
              </para>
            </listitem>
            <listitem>
              <para>
                if patch is modified version of something found in the 
                net, you should mention both the original sources,
                and the fact, that you modified it
              </para>
            </listitem>
          </orderedlist>
          In case of initial import of spec file you should mention
          where does the spec come from (<literal>"- from 
          scratch"</literal>, <literal>"- roughly based on spec from
          MDK; rewritten"</literal> are both OK). There is no need 
          to cite <literal>Summary:</literal> there.
        </para>
      </listitem>
      <listitem>
        <para>
          Patch names should have format: 
          <filename>PACKAGE-what-patch-fixes.patch</filename>. They should
          be in unified diff format 
          (<command>diff -urN original-tree/ fixed-tree/</command> 
          is good way of preparing such beasts). Name should not
          contain version number.
        </para>
        <para>
          This is all true, <emphasis>unless</emphasis> patch is unmodified
          version of something that has URL. Leave it then as it stands.
        </para>
      </listitem>
      <!--
      <listitem>
        <para>
          <emphasis>
          </emphasis>
        </para>
        <para>
        </para>
      </listitem>
      -->
    </orderedlist>
  </para>
</section>
