<h1>KDE CVS Commit Policy</h1>
<p>Version 1.0 (April 2003)</p>
<h2>Summary</h2>
<ol>
<li><a href="#1">Think twice before committing.</a></li>
<li><a href="#2">Never commit code that doesn't compile.</a></li>
<li><a href="#3">Test your changes before committing</a>.</li>
<li><a href="#4">Double check what you commit.</a></li>
<li><a href="#5">Always add descriptive log messages.</a></li>
<li><a href="#6">The code you commit has to adhere to the KDE coding
policies.</a></li>
<li><a href="#7">Respect special commit policies set by the release
plans.</a></li>
<li><a href="#8">Respect the policies of application and library maintainers,
and consult with them before making large changes.</a></li>
<li><a href="#9">When you plan to do changes which affect a lot of different
code in CVS announce them on the mailing list in advance.</a></li>
<li><a href="#10">Don't commit changes to the public API of libraries without
prior review by other developers.</a></li>
<li><a href="#11">Take responsibilty for your commits.</a></li>
<li><a href="#12">Don't commit code you don't understand.</a></li>
<li><a href="#13">Don't abuse your CVS account to push in changes which are
disagreed by other developers.</a></li>
<li><a href="#14">If you commit bugfixes think about porting the fixes to
other branches.</a></li>
<li><a href="#15">If you fix bugs reported on the bug tracking system add the
bug number to the log message.</a></li>
<li><a href="#16">Avoid losing CVS history by renaming or moving
files.</a></li>
<li><a href="#17">Official KDE release and branch tags use upper case. Use
lower case tags for all other tags and branches.</a></li>
<li><a href="#18">Don't add generated files to the repository.</a></li>
<li><a href="#19">Don't use CVS keywords like <em>Id</em> or <em>Log</em> in
the source files.</a></li>
<li><a href="#20">Do "atomic" commits.</a></li>
<li><a href="#21">Don't mix formatting changes with code changes.</a></li>
</ol>
<h2>Details</h2>
<ol>
<li>
<p><b><a name="1">Think twice before committing.</a></b></p>
<p>Committing something to CVS has serious consequences. All other
developers will get your changes once they are in CVS and if they break
something they will break it for everybody. All commits will be publically
available in the CVS repository forever.</p>
<p>On the other hand CVS allows to revert changes, so it's possible to
recover from mistakes. This is relatively easy for commits to single files
but it can also be a significant amount of work for bigger changes.</p>
<p>The baseline is: Be aware of the consequences of your commits. Take your
time to think about them before committing.</p>
<p/>
</li>
<li>
<p><b><a name="2">Never commit code that doesn't compile.</a></b></p>
<p>Compile the code and correct all errors before committing. Make sure that
newly added files are comitted. If they are missing your local compile will
work fine but everybody else won't be able to compile.</p>
<p>You certainly should make sure that the code compiles with your local
setup. You should also consider what consequences your commit will have for
compiling with the source directory being different from the build
directory. It would also be nice if it would compile with the --enable-final
option, but we don't explicitly support that.</p>
<p>Be exepcially careful if you change the build system, i.e. Makefiles</p>
<p/>
</li>
<li>
<p><b><a name="3">Test your changes before committing.</a></b></p>
<p>Start the application affected by your change and try if the changed code
behaves as desired.</p>
<p>Run regression tests if available ("make check").</p>
<p/>
</li>
<li>
<p><b><a name="4">Double check what you commit.</a></b></p>
<p>Do a "cvs update" and a "cvs diff" before committing. Take messages from
CVS about conflicts, unknown files etc seriously. The "cvs diff" will tell
you exactly what you will be committing. Check if that's really what you
intended to commit.</p>
<p/>
</li>
<li>
<p><b><a name="5">Always add descriptive log messages.</a></b></p>
<p>Log messages should be understandable by somebody who only sees the log.
They shouldn't depend on information outside the context of the commit. Try
to put the log messages to only the files which are really affected by the
change described in the log message.</p>
<p>In particular put all important information which can't be seen from the
diff in the log message.</p>
<p/>
</li>
<li>
<p><b><a name="6">The code you commit has to adhere to the KDE coding
policies.</a></b></p>
<p>This includes security (shell quoting, buffer overflows, format string
vulnerabilities), binary compatibility (d pointers), i18n, usability, user
interface style guide, (API) documentation, documentation and definition of
memory management and ownership policies, method naming, conditions for
inclusion in kdelibs, portability issues.</p>
<p>These policies are defined separately. If in doubt ask on the mailing
list.</p>
<p/>
</ul>
<li>
<p><b><a name="7">Respect special commit policies set by the release
plans.</a></b></p>
<p/>
</li>
<li>
<p><b><a name="8">Respect the policies of application and library
maintainers, and consult with them before making large changes.</a></b></p>
<p>Source control systems are not a substitute for developer
communication.</p>
<p/>
</li>
<li>
<p><b><a name="9">When you plan to do changes which affect a lot of
different code in CVS announce them on the mailing list in
advance.</a></b></p>
<p>Changes which affect a lot of code in CVS, like making use of a new
feature in the libs, might break other code even if they look trivial, e.g.
because an application also have to compile with older versions of the libs
for some reasons. By announcing the changes in advance developers are
prepared and can express concerns before something gets broken.</p>
<p/>
</li>
<li>
<p><b><a name="10">Don't commit changes to the public API of libraries
without prior review by other developers.</a></b></p>
<p>There are certain special requirements for the public APIs of the KDE
libraries, e.g source and binary compatibility issues. Changes to the public
APIs affect many other KDE developers including third party developers, so
requiring a review for these changes is intended to avoid problems for the
users of the APIs and to improve the quality of the APIs.</p>
<p/>
</li>
<li>
<p><b><a name="11">Take responsibilty for your commits.</a></b></p>
<p>If your commit breaks something or has side effects on other code, take
the responsibility to fix or help fixing the problems.</p>
<p/>
</li>
<li>
<p><b><a name="12">Don't commit code you don't understand.</a></b></p>
<p>Avoid things like "I don't know why it crashes, but when I do this, it
does not crash anymore." or "I don't know what happens, but till somebody
finds out, I'm disabling it". or "I'm not completely sure if thats right,
but at least it works for me.".</p>
<p>If you don't find a solution to a problem discuss it with other
developers.</p>
<p/>
</li>
<li>
<p><b><a name="13">Don't abuse your CVS account to push in changes which
are disagreed by other developers.</a></b></p>
<p>If there are controversials about code changes these should be resolved
by discussing them on the mailing lists or in private not by forcing code on
others by just committing it to CVS.</p>
<p/>
</li>
<li>
<p><b><a name="14">If you commit bugfixes think about porting the fixes to
other branches.</a></b></p>
<p>Use the same comment for both the original fix and the
backport, that way it is easy to see which fixes have been backported
already.</p>
<p/>
</li>
<li>
<p><b><a name="15">If you fix bugs reported on the bug tracking system add
the bug number to the log message.</a></b></p>
<p>In order to keep the bug tracking system in sync with CVS you should
reference the bug report in your commits and close the fixed bugs in the bug
tracking system.</p>
<p/>
</li>
<li>
<p><b><a name="16">Avoid losing CVS history by renaming or moving
files.</a></b></p>
<p>As an alternative to renaming or moving files by using CVS commands they
can be moved on the server. Ask sysadmin@kde.org to do this if you need to
rename or move files in the CVS repository.</p>
<p/>
</li>
<li>
<p><b><a name="17">Official KDE release and branch tags use upper case.
Use lower case tags for all other tags and branches.</a></b></p>
<p/>
</li>
<li>
<p><b><a name="18">Don't add generated files to the repository.</a></b></p>
<p>Files generated at build time like moc files, the files generated from ui
files or Makefiles shouldn't be checked into the repository because this is
redundant information and might cause conflicts. Only real source file
should be in CVS.</p>
<p/>
</li>
<li>
<p><b><a name="19">Don't use CVS keywords like <em>Id</em> or <em>Log</em>
in the source files.</a></b></p>
<p>These tags cause unnecessary conflicts when merging branches and don't
contain any information which wouldn't be available in the CVS repository
anyway.</p>
<p/>
</li>
<li>
<p><b><a name="20">Do "atomic" commits.</a></b></p>
<p>CVS has the ability to commit more than one file at a time. Please
therefore commit all related changes in multiple files at the same time in
the same commit. This way you ensure that CVS stays in a compileable state
before and after the commit. </p>
<p/>
</li>
<li>
<p><b><a name="21">Don't mix formatting changes with code
changes.</a></b></p>
<p>Changing formatting like indenting or whitespaces blows up the diff, so
that it is hard to find code changes if they are mixed with reindenting
commits or similar things when looking at the logs and diffs later. doing
formatting changes in a separate commit solves this problem.</p>
<p/>
</li>
</ol>
<h2>Appendix: Special keywords in CVS log messages</h2>
<p>Adding these keywords to the commit log will trigger special actions.</p>
<dl>
<dt>GUI</dt> <dd>Mark user visible change of GUI.</dd>
<dt>CCMAIL</dt> <dd>Send commit mail to given mail address in addition to
kde-cvs@kde.org.</dd>
<dt>CVS_SILENT</dt> <dd>nonverbose commit log</dd>
</dl>
<hr/>
<em>This page is maintained by <a href="mailto:schumacher@kde.org">Cornelius
Schumacher</em>