KDE CVS Commit Policy (2nd version)
Cornelius Schumacher
kde-policies@mail.kde.org
Mon, 31 Mar 2003 02:05:51 +0200
--Boundary-00=_fZ4h+MinDzk2U/n
Content-Type: text/plain;
charset="us-ascii"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
Attached to this mail you find the second version of the draft for a CVS
Commit Policy. I tried to incorporate all comments. Thanks for the
input so far. Please have a look and send more comments ;-).
--
Cornelius Schumacher <schumacher@kde.org>
--Boundary-00=_fZ4h+MinDzk2U/n
Content-Type: text/plain;
charset="us-ascii";
name="commitpolicy.txt"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="commitpolicy.txt"
KDE CVS Commit Policy
=====================
Summary:
--------
1. Think twice before committing.
2. Never commit code that doesn't compile.
3. Test your changes before committing.
4. Always add descriptive log messages.
5. The code you commit has to adhere to the KDE coding policies.
6. Respect special commit policies set by the release plans.
7. Respect the policies of application and library maintainers, and consult
with them before making large changes.
8. When you plan to do changes which affect a lot of different code in CVS
announce them on the mailing list in advance.
9. Don't commit changes to the public API of libraries without prior review by
other developers.
10. Take responsibilty for your commits.
11. Don't commit code you don't understand.
12. Don't abuse your CVS account to push in changes which are disagreed by other
developers.
13. If you commit bugfixes think about porting the fixes to other branches.
14. If you fix bugs reported on the bug tracking system add the bug number to
the log message.
15. Avoid losing CVS history by renaming or moving files.
16. Official KDE release and branch tags use upper case. Use lower case tags for
all other tags and branches.
17. Don't add generated files to the repository.
18. Don't use CVS keywords like $Id$ or $Log$ in the source files.
Details:
--------
1. Think twice before committing.
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.
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.
The baseline is: Be aware of the consequences of your commits. Take your
time to think about them before committing.
2. Never commit code that doesn't compile.
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.
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.
Be exepcially careful if you change the build system, i.e. Makefiles
3. Test your changes before committing.
Start the application affected by your change and try if the changed code
behaves as desired.
Run regression tests if available ("make check").
4. Always add descriptive log messages.
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.
In particular put all important information which can't be seen from the
diff in the log message.
5. The code you commit has to adhere to the KDE coding policies.
This includes security (shell quoting, buffer overflows, format string
vulnerabilities), binary compatibility (d pointers), i18n, usability, user
interface style guide, (API) documentation, coding style (spaces vs tabs,
indentation, curly bracket placement), documentation and definition of
memory management and ownership policies, method naming, conditions for
inclusion in kdelibs, portability issues.
These policies are defined separately. If in doubt ask on the mailing list.
6. Respect special commit policies set by the release plans.
7. Respect the policies of application and library maintainers, and consult
with them before making large changes.
Source control systems are not a substitute for developer communication.
8. When you plan to do changes which affect a lot of different code in CVS
announce them on the mailing list in advance.
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.
9. Don't commit changes to the public API of libraries without prior review by
other developers.
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.
10. Take responsibilty for your commits.
If your commit breaks something or has side effects on other code, take the
responsibility to fix or help fixing the problems.
11. Don't commit code you don't understand.
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.".
If you don't find a solution to a problem discuss it with other developers.
12. Don't abuse your CVS account to push in changes which are disagreed by other
developers.
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.
13. If you commit bugfixes think about porting the fixes to other branches.
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.
14. If you fix bugs reported on the bug tracking system add the bug number to
the log message.
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.
15. Avoid losing CVS history by renaming or moving files.
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.
16. Official KDE release and branch tags use upper case. Use lower case tags for
all other tags and branches.
17. Don't add generated files to the repository.
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.
18. Don't use CVS keywords like $Id$ or $Log$ in the source files.
These tags cause unnecessary conflicts when merging branches and don't
contain any information which wouldn't be available in the CVS repository
anyway.
Appendix: Special keywords in CVS log messages
----------------------------------------------
GUI: Mark user visible change of GUI.
CCMAIL: Send commit mail to given mail address in addition to kde-cvs@kde.org.
--Boundary-00=_fZ4h+MinDzk2U/n--