mirror of https://github.com/tLDP/LDP
229 lines
6.7 KiB
XML
229 lines
6.7 KiB
XML
<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>
|