Committing something to SVN has serious consequences. All other developers will get your changes once they are in SVN, and if they break something, they will break it for everybody. All commits will be publicly available in the SVN repository forever.

+

Committing something to KDE's codebase has serious consequences. All other developers will get your changes once they are in the git repository, and if they break something, they will break it for everybody. All commits will be publicly available in the git repository forever.

−

On the other hand SVN allows one 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.

+

On the other hand git allows one 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 time to think about them before committing.

The baseline is: Be aware of the consequences of your commits. Take time to think about them before committing.

=== Never commit code that doesn't compile ===

=== 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.

+

Compile the code and correct all errors before committing. Make sure that newly added files are committed. 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 <tt>--enable-final</tt> option, but we don't explicitly support that.

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 <tt>--enable-final</tt> option, but we don't explicitly support that.

Line 16:

Line 16:

Start the application affected by your change and make sure that the changed code behaves as desired.

Start the application affected by your change and make sure that the changed code behaves as desired.

−

Run regression tests if available (<tt>make check</tt>).

+

Run unit and regression tests, if available (KDE4: <tt>make test</tt>, KDE3: <tt>make check</tt>).

=== Double check what you commit ===

=== Double check what you commit ===

−

Do a <tt>svn update</tt> and a <tt>svn diff</tt> before committing. Take messages from SVN about conflicts, unknown files, etc. seriously. ''svn diff'' will tell you exactly what you will be committing. Check if that's really what you intended to commit.

+

Do a <tt>git pull --rebase</tt> to keep your checkout up-to-date. Invoke <tt>git diff</tt> before committing. Take messages from git about conflicts, unknown files, etc. seriously. ''git diff'' will tell you exactly what you will be committing. Check if that's really what you intended to commit.

+

+

You can find further help on [http://techbase.kde.org/Development/Git how to use git on techbase]. In addition, you can use <tt>gitk</tt> and [http://git-cola.github.io/ git-cola] as graphical tools.

=== Always add descriptive log messages ===

=== Always add descriptive log messages ===

Line 32:

Line 34:

=== Respect commit policies set by the Release Plans ===

=== Respect commit policies set by the Release Plans ===

+

+

Among other things, it means that binary-incompatible changes (BIC) to unreleased APIs in trunk should only happen on Mondays.

=== Respect other developer's code ===

=== Respect other developer's code ===

Line 39:

Line 43:

=== Announce changes in advance ===

=== Announce changes in advance ===

−

When you plan to make changes which affect a lot of different code in SVN, announce them on the mailing list in advance. For instance, changes in libraries might break other code even if they look trivial, e.g., because an application must also compile with older versions of the librariy for some reasons. By announcing the changes in advance, developers are prepared, and can express concerns before something gets broken.

+

When you plan to make changes which affect a lot of different code in KDE's codebase, announce them on the mailing list in advance. For instance, changes in libraries might break other code even if they look trivial, e.g., because an application must also compile with older versions of the library for some reasons. By announcing the changes in advance, developers are prepared, and can express concerns before something gets broken.

=== Code review by other developers ===

=== Code review by other developers ===

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.

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.

−

=== Take responsibilty for your commits ===

+

=== Take responsibility for your commits ===

If your commit breaks something or has side effects on other code, take the responsibility to fix or help fix the problems.

If your commit breaks something or has side effects on other code, take the responsibility to fix or help fix the problems.

=== Don't commit code you don't understand ===

=== 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'm not completely sure if thats right, but at least it works for me.".

+

Avoid things like "I don't know why it crashes, but when I do this, it does not crash anymore." or "I'm not completely sure if that's right, but at least it works for me.".

If you don't find a solution to a problem, discuss it with other developers.

If you don't find a solution to a problem, discuss it with other developers.

=== Don't commit if other developers disagree ===

=== Don't commit if other developers disagree ===

−

If there are disagreements over code changes, these should be resolved by discussing them on the mailing lists or in private, not by forcing code on others by simply committing the changes to SVN.

+

If there are disagreements over code changes, these should be resolved by discussing them on the mailing lists or in private, not by forcing code on others by simply committing the changes.

=== Backport bugfixes ===

=== Backport bugfixes ===

Line 59:

Line 63:

=== Use bug tracking system numbers ===

=== Use bug tracking system numbers ===

−

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 SVN, you should reference the bug report in your commits, and close the fixed bugs in the bug tracking system.

+

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 the git repositories, you should reference the bug report in your commits, and close the fixed bugs in the bug tracking system.

This doesn't mean that you don't need an understandable log message. It should be clear from the log message what has been changed without looking at the bug report.

This doesn't mean that you don't need an understandable log message. It should be clear from the log message what has been changed without looking at the bug report.

Line 71:

Line 75:

=== Don't add generated files to the repository ===

=== Don't add generated files to the repository ===

−

Files generated at build time shouldn't be checked into the repository because this is redundant information and might cause conflicts. Only real source files should be in SVN. An exception to that are files generated by tools that would be an unusual requirement for building KDE.

+

Files generated at build time shouldn't be checked into the repository because this is redundant information and might cause conflicts. Only real source files should be in the git repositories. An exception to that are files generated by tools that would be an unusual requirement for building KDE.

Standard tools include gcc, g++, cmake, /bin/sh, perl, moc, uic and the tools part of KDE itself. Tools needed for KDE applications written in non-C++ are allowed as well (e.g. python, ruby).

Standard tools include gcc, g++, cmake, /bin/sh, perl, moc, uic and the tools part of KDE itself. Tools needed for KDE applications written in non-C++ are allowed as well (e.g. python, ruby).

Line 77:

Line 81:

Tools which shouldn't be a requirement for building KDE include lex/flex, yacc/bison, python, ruby etc.

Tools which shouldn't be a requirement for building KDE include lex/flex, yacc/bison, python, ruby etc.

−

=== Don't use SVN keywords in source files ===

+

=== Commit complete changesets ===

−

SVN keywords like <tt>Id</tt> or <tt>Log</tt> cause unnecessary conflicts when merging branches and don't contain any information which wouldn't be available in the SVN repository anyway.

+

git has the ability to commit more than one file at a time. Therefore, please commit all related changes in multiple files, even if they span over multiple directories at the same time in the same commit. This way, you ensure that git stays in a compilable state before and after the commit, that the commit history (svn log) is more helpful and that the kde-commits mailing list is not flooded with useless mails.

−

=== Make "atomic" commits ===

+

OTOH, commits should be preferably "atomic" - not splittable. That means that every bugfix, feature, refactoring or reformatting should go into an own commit. This, too, improves the readability of the history. Additionally, it makes porting changes between branches (cherry-picking) and finding faulty commits (by bisecting) simpler.

−

SVN has the ability to commit more than one file at a time. Therefore, please commit all related changes in multiple files, even if they span over multiple directories at the same time in the same commit. This way, you ensure that SVN stays in a compileable state before and after the commit.

+

While most KDE developers do not pay much attention to that rule, some do so very much. Consequently, you should be very careful about it when making commits in areas which you do not maintain.

=== Don't mix formatting changes with code changes ===

=== Don't mix formatting changes with code changes ===

−

Changing formatting like indenting or white spaces 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. Committing formatting changes separately solves this problem.

+

Changing formatting like indenting or white spaces blows up the diff, so that it is hard to find code changes if they are mixed with re-indenting commits or similar things when looking at the logs and diffs later. Committing formatting changes separately solves this problem.

=== GUI Changes ===

=== GUI Changes ===

If your commit causes user visible GUI changes, add the <tt>GUI</tt> keyword to the log message. This makes sure that the documentation writers get notified of your changes.

If your commit causes user visible GUI changes, add the <tt>GUI</tt> keyword to the log message. This makes sure that the documentation writers get notified of your changes.

−

== Special keywords in SVN log messages ==

+

== Special keywords in GIT and SVN log messages ==

−

When you commit changes to SVN you will be asked for a description of your commit. There are several special keywords defined that you can use in this description. These keywords are always uppercase and followed by a colon. Each keyword should be placed on a line of its own. The following keywords can be used.

+

When you commit changes to git (or SVN) you will be asked for a description of your commit. There are several special keywords defined that you can use in this description. These keywords are always uppercase.

−

* '''BUG:''' ''<bugnumber>''<br/>Marks the bug as closed by CC'ing the commit message to <bugnumber>-done@bugs.kde.org This keyword will also be used to automatically extract entries for the release changelog.

+

−

* '''CCBUG:''' ''<bugnumber>''<br/>CC's to the bugreport by sending mail to <bugnumber>@bugs.kde.org

+

The following keywords are pseudo-headers - they have to appear at the start of a line and be followed by a colon:

−

* '''CCMAIL:''' <email-address><br/>CC's to the given e-mail address.

+

−

* '''SVN_SILENT:'''<br/>Marks the commit message "silent" by adding "(silent)" to the subject of the mail to allow filtering out trivial commits. Use this tag carefully and only for really uninteresting, uncontroversial commits.

+

* '''FEATURE:''' [''<bugnumber>'']<br/>Marks the feature as implemented by CC'ing the commit message to <bugnumber>-done@bugs.kde.org. This keyword will also be used to automatically extract entries for the release changelog, so it makes sense to use it for new features even if you don't have a bugnumber for the feature.

* '''FEATURE:''' [''<bugnumber>'']<br/>Marks the feature as implemented by CC'ing the commit message to <bugnumber>-done@bugs.kde.org. This keyword will also be used to automatically extract entries for the release changelog, so it makes sense to use it for new features even if you don't have a bugnumber for the feature.

+

* '''BUG:''' ''<bugnumber>''<br/>Marks the bug as fixed by CC'ing the commit message to <bugnumber>-done@bugs.kde.org. This keyword will also be used to automatically extract entries for the release changelog.

+

** '''FIXED-IN:''' ''<version>''<br/>If the '''BUG''' keyword is used to close a bug, this keyword will update the bug's ''release version'' that the fix appears in. You can only select one version, so prefer the lowest release version that will actually have the fix.

+

* '''CCBUG:''' ''<bugnumber>''<br/>CC's to the bugreport by sending mail to <bugnumber>@bugs.kde.org

+

* '''CCMAIL:''' ''<email-address>''<br/>CC's to the given e-mail address.

+

* '''REVIEW:''' ''<reviewnumber>''<br />Closes the review on Reviewboard and adds a comment which refers to the commit.

* '''GUI:'''<br/>Indicates a user visible change in the user interface. This is used to make the documentation team aware of such changes.

* '''GUI:'''<br/>Indicates a user visible change in the user interface. This is used to make the documentation team aware of such changes.

+

* '''DIGEST:'''<br />Notifies the KDE Commit Digest team of interesting/important commits to look at (for easy collection, summarization and presentation of commits to end-users).

+

+

This keyword can appear anywhere on a line:

+

* '''SVN_SILENT'''<br/>Marks the commit message "silent" by adding "(silent)" to the subject of the mail to allow filtering out trivial commits. Use this tag carefully and only for really uninteresting, uncontroversial commits.

+

+

* '''SVN_MERGE'''<br/>Special keyword for people that use the svnmerge script. Marks the commit message as being a merge commit by adding "(merge)" to the subject of the mail. This way receivers can filter out mails that are caused by merging the same patch from one branch to another branch. Reviews of those mails is usually not needed. This keyword filters out the endless property changes used by this script.

Guidelines

Think Twice before Committing

Committing something to KDE's codebase has serious consequences. All other developers will get your changes once they are in the git repository, and if they break something, they will break it for everybody. All commits will be publicly available in the git repository forever.

On the other hand git allows one 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 time to think about them before committing.

Never commit code that doesn't compile

Compile the code and correct all errors before committing. Make sure that newly added files are committed. 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 especially careful if you change the build system, i.e. Makefiles

Test your changes before committing

Start the application affected by your change and make sure that the changed code behaves as desired.

Run unit and regression tests, if available (KDE4: make test, KDE3: make check).

Double check what you commit

Do a git pull --rebase to keep your checkout up-to-date. Invoke git diff before committing. Take messages from git about conflicts, unknown files, etc. seriously. git diff will tell you exactly what you will be committing. Check if that's really what you intended to commit.

Always add descriptive log messages

Log messages should be understandable to someone who sees only the log. They shouldn't depend on information outside the context of the commit. Try to put the log messages only to those 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.

These policies are defined separately. If in doubt ask on the mailing list.

Respect commit policies set by the Release Plans

Among other things, it means that binary-incompatible changes (BIC) to unreleased APIs in trunk should only happen on Mondays.

Respect other developer's code

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.

Announce changes in advance

When you plan to make changes which affect a lot of different code in KDE's codebase, announce them on the mailing list in advance. For instance, changes in libraries might break other code even if they look trivial, e.g., because an application must also compile with older versions of the library for some reasons. By announcing the changes in advance, developers are prepared, and can express concerns before something gets broken.

Code review by other developers

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.

Take responsibility for your commits

If your commit breaks something or has side effects on other code, take the responsibility to fix or help fix the problems.

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'm not completely sure if that's right, but at least it works for me.".

If you don't find a solution to a problem, discuss it with other developers.

Don't commit if other developers disagree

If there are disagreements over code changes, these should be resolved by discussing them on the mailing lists or in private, not by forcing code on others by simply committing the changes.

Backport bugfixes

If you commit bugfixes, consider 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.

Use bug tracking system numbers

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 the git repositories, you should reference the bug report in your commits, and close the fixed bugs in the bug tracking system.

This doesn't mean that you don't need an understandable log message. It should be clear from the log message what has been changed without looking at the bug report.

Tags and branches

There are rules for where to place release tags and branches in the repository. Official KDE branches and release will be created by the release KDE coordinator in the branches/KDE and tags/KDE directories, scripts will ensure that this folders are protected.

Developers should place all branches which are aimed to be released in branches/appname and name them like the release, e.g. branches/appname/1.5. For all release tags, tags/appname is the right place.

All temporary working branches (which should be deleted again after the work has ended) should be located in branches/work with some name describing both which part of KDE (or which application) is branched and which work is done there. A good example would be branches/work/khtml-paged for a khtml working branch to include paged media support. Bad idea would be something like branches/work/make-it-cool.

Don't add generated files to the repository

Files generated at build time shouldn't be checked into the repository because this is redundant information and might cause conflicts. Only real source files should be in the git repositories. An exception to that are files generated by tools that would be an unusual requirement for building KDE.

Standard tools include gcc, g++, cmake, /bin/sh, perl, moc, uic and the tools part of KDE itself. Tools needed for KDE applications written in non-C++ are allowed as well (e.g. python, ruby).

Tools which shouldn't be a requirement for building KDE include lex/flex, yacc/bison, python, ruby etc.

Commit complete changesets

git has the ability to commit more than one file at a time. Therefore, please commit all related changes in multiple files, even if they span over multiple directories at the same time in the same commit. This way, you ensure that git stays in a compilable state before and after the commit, that the commit history (svn log) is more helpful and that the kde-commits mailing list is not flooded with useless mails.

OTOH, commits should be preferably "atomic" - not splittable. That means that every bugfix, feature, refactoring or reformatting should go into an own commit. This, too, improves the readability of the history. Additionally, it makes porting changes between branches (cherry-picking) and finding faulty commits (by bisecting) simpler.
While most KDE developers do not pay much attention to that rule, some do so very much. Consequently, you should be very careful about it when making commits in areas which you do not maintain.

Don't mix formatting changes with code changes

Changing formatting like indenting or white spaces blows up the diff, so that it is hard to find code changes if they are mixed with re-indenting commits or similar things when looking at the logs and diffs later. Committing formatting changes separately solves this problem.

GUI Changes

If your commit causes user visible GUI changes, add the GUI keyword to the log message. This makes sure that the documentation writers get notified of your changes.

Special keywords in GIT and SVN log messages

When you commit changes to git (or SVN) you will be asked for a description of your commit. There are several special keywords defined that you can use in this description. These keywords are always uppercase.

The following keywords are pseudo-headers - they have to appear at the start of a line and be followed by a colon:

FEATURE: [<bugnumber>]Marks the feature as implemented by CC'ing the commit message to <bugnumber>-done@bugs.kde.org. This keyword will also be used to automatically extract entries for the release changelog, so it makes sense to use it for new features even if you don't have a bugnumber for the feature.

BUG:<bugnumber>Marks the bug as fixed by CC'ing the commit message to <bugnumber>-done@bugs.kde.org. This keyword will also be used to automatically extract entries for the release changelog.

FIXED-IN:<version>If the BUG keyword is used to close a bug, this keyword will update the bug's release version that the fix appears in. You can only select one version, so prefer the lowest release version that will actually have the fix.

CCBUG:<bugnumber>CC's to the bugreport by sending mail to <bugnumber>@bugs.kde.org

CCMAIL:<email-address>CC's to the given e-mail address.

REVIEW:<reviewnumber>Closes the review on Reviewboard and adds a comment which refers to the commit.

GUI:Indicates a user visible change in the user interface. This is used to make the documentation team aware of such changes.

DIGEST:Notifies the KDE Commit Digest team of interesting/important commits to look at (for easy collection, summarization and presentation of commits to end-users).

This keyword can appear anywhere on a line:

SVN_SILENTMarks the commit message "silent" by adding "(silent)" to the subject of the mail to allow filtering out trivial commits. Use this tag carefully and only for really uninteresting, uncontroversial commits.

SVN_MERGESpecial keyword for people that use the svnmerge script. Marks the commit message as being a merge commit by adding "(merge)" to the subject of the mail. This way receivers can filter out mails that are caused by merging the same patch from one branch to another branch. Reviews of those mails is usually not needed. This keyword filters out the endless property changes used by this script.