Policies/Commit Policy

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.

Git allows reverting changes, so it's possible to recover from mistakes. Bit it's best to avoid making them in the first place.

The bottom line is: be aware of the consequences of your commits. Consider the following guidelines:

Before committing

Announce large changes in advance: when you plan to make changes which affect a lot of different repositories, announce them in advance on a relevant mailing list or Matrix room

Honor 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, documentation and definition of memory management and ownership policies, method naming, conditions for inclusion in KDE Frameworks, portability issues and license notices.

Respect other developer's code: don't change code style just because you don't like it. Solve real problems; don't just re-arrange the code.

Don't mix formatting changes with code changes: split these into separate commits.

Test your changes before committing: make sure the changes compile, have the effect you're expecting, and don't regress anything else. Run unit and regression tests (if available) with the ctest command.

Don't commit code you don't understand: avoid things like "I don't know why it crashes, but when I do this, it doesn't crash anymore." Understand your changes. If you can't find a solution to a problem that you understand, 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

Don't add generated files to the repository: only real source files should be in the git repositories.

Commit atomic changesets: every bugfix, feature, refactoring, or reformatting should go into its own commit. This improves the readability of the history, makes it easier to port changes between branches, and makes it easier to find faulty commits using git bisect.

Double-check before committing: do a final 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.

Write a good commit message

Follow the general rules of a good commit message: https://community.kde.org/Infrastructure/GitLab#Write_a_good_commit_message

Use relevant keywords in commit messages: see Infrastructure/Git/Hooks#Keywords.

Make your commit message comprehensible without context: what has been changed should still be clear from the commit message without looking at any referenced URLs or bug reports.

After committing

Don't push directly to master: instead, get code review by other developers by submitting a merge request.

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.

Backport bugfixes: if you commit bugfixes, consider porting the fixes to bugfix/release branches. Use git cherry-pick -x for this.

Document noteworthy changes: If your change is something that you consider exciting enough to be listed in its product's public user-facing release notes, write it down in [Plasma/Plasma_6#Per-version_changes] or any other similar location.

Learn more

Here is further help on how to use git. In addition, you can use git graphical tools. The git project contains "git gui" and "gitk". You can use other git GUI tools, e.g. git-cola, gitg. See https://git-scm.com/tools/guis.