Projects/Kate/Commit Policy

THIS IS A DRAFT

This document is a work in progress, and may be incomplete and / or inaccurate.

Please help improve it!

About this document

So you want to participate in developing kate? Great! The project is always in need of helping hands.

However, trying to help, and being helpful is not always the same thing. Therefore, we would like to ask you to read through this document, before you start committing to this repository. We try to keep this text short, and limit it to some of the most important pitfalls, only, and we will focus mostly on issues which are specific to kate, as opposed to generic guidelines. Common sense applies.

In writing this document, we will assume that you have developer access to the repository. However, if you don't, the same basic rules apply for sending patches, too.

General rules

1. If you have the slightest doubt, ask!
   • This is probably the most important rule. Communicate, discuss, ask questions.
   • For small technical questions, the fatest way to get an answer is typically IRC (irc://irc.kde.org/kate for the kate specific channel; often irc://irc.kde.org/kde-devel is also a good place to ask).
   • For questions that may need a broader discussion, or some time to think about, the mailing list is generally the best place to ask: [email protected] . In fact, if you plan to contribute more than just once, it is highly recommended that you subscribe.
   • For feedback on a concrete patch, reviewboard.kde.org is suited, best.
2. Understand what you are doing.
   • Do not commit code that you don't understand, even if it appears to fix problems. Ask instead (see above).
3. Test you code.
   • Test your code to make sure it really does what you think it does. Then test that it doesn't break anything. Then test again.
4. Respect schedules and agreements.
   • Make sure you are aware of the current Release Schedules, and the associated freezes in the different branches.
   • Generally it is a good idea to have a look at the last few weeks of the mailing list archive, to see if there may be any reasons against committing certain changes at that time.
   • If in any doubt: Ask.
5. Respect copyright and licences.
   • In the open source world, a lot of copying and re-use of code is permitted. But please make sure you have checked and understood the applicable terms, in each case.
   • If in any doubt: Ask.
6. Use bugs.kde.org
   • If the bug you are about to fix has been annoying you for ages, probably others have noted it before, too. If you think the feature you're about to implement is a must have, then others might have had the same idea. Please be sure to check bugs.kde.org for existing reports / requests. This might contain important considerations that you did not think about, yet. And of course it is important to close the corresponding reports after the bug has been fixed / feature committed, in order to keep bug database manageable. Taking some time for bookkeeping is an important part of developing in a community project.

Coding style

1. Respect coding conventions and style, kate.git follows the kdelibs coding style.
   • Don't just write in your personal style. Tastes differ, and if we mix all sorts of styles, the code just gets harder to read.
   • In general, please try to follow the coding style of the surrounding code.
2. Use four spaces to indent.
3. Whenever possible use title case includes without directory, e.g. #include <QLabel>

Kate specific rules

The main sub-directories of this repository are "kate" and "kwrite". Very different guidelines apply to these, so make sure you understand what is or is not allowed in each sub-project.

kate / kwrite

These directories hold code that is specific to the stand-alone applications kate and kwrite. As such it is application code, and this means that, generally, there is no need to care about source or binary compatibility. Changes in this directory do not affect applications other than kate or kwrite, and thus they are relatively safe. However, please be aware that both kate and kwrite are productivity tools, used extensively by a large userbase. Often, these users will use kate/kwrite in ways that you have never even thought about, or use features, which even core contributors may not be aware of. Please be careful that you don't break existing features and workflows, unless you have very good reason to do so. If in any doubt: Ask.

When implementing new features, please take a moment to think about whether they be limited to kate, or whether they should be implemented in the kate part, in order to make them accessible to all applications using katepart. As a generic rule of thumb: If the feature (or a similar feature) could be useful in kwrite, then it should probably go into katepart. If the feature might be useful in applications such as kdevelop, kile, quanta, rkward, etc. then it should probably be implemented in katepart. If in any doubt: Ask.