1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
== 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 comitting 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 ==
# 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: kwrite-devel@kde.org . 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.
# 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).
# 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.
# Respect schedules and agreements.
#* Make sure you are aware of the current [http://techbase.kde.org/Schedules 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 [http://lists.kde.org/?l=kwrite-devel&r=1&w=2 mailing list archive], to see if there may be any reasons against committing certain changes at that time.
#* If in any doubt: Ask.
# Respect coding conventions and 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. For more in-depth information, refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style .
# 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.
# 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 managable. Taking some time for bookkeeping is an important part of developing in a community project.
== Kate specific rules ==
The main sub-directories of this repository are "kate", "kwrite", "part", and "ktexteditor". Very
differnt 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.
=== part ===
This directory holds the implementation of the kate "part". We assume that you know what a KPart is (and if you don't,
then please read up on it), but as a short summary: Any KDE application can embed this part, in order to gain advanced
text-editor features in very few lines of code. And many, many applications do, inside and outside of kde.org.
These external applications are not compiled or linked against the katepart. Thus many concerns about source and binary
compatibility do not apply. However, several types of changes in katepart code can potentially have non-obvious
negative side-effects on applications that embed katepart. Thus, please be sure you understand the following issues,
and think twice before doing such changes:
# Shortcuts
#* Embedding applications will typically inherit the complete GUI from katepart, including all shortcuts. More often than not, these applications will also define a considerable number of application-specific shortcuts in addition to that. This has a lot of potential to create clashes between shortcuts in the katepart, and the
embedding application. Thus, please think twice before adding new shortcuts, or changing the default keys for existing shortcuts. Ask yourself: Does this action really need a shortcut ''by default''?
# Action names
#* The names of actions and menus may seem like a fully internal implementation detail, on first glance. But they are not. In fact embedding applications sometimes have the need to hide specific actions, to re-arrange them, or to modify them in other ways (e.g. changing the text to avoid ambiguities, etc.). To do so, they will reference the actions by their id / name (not their text label). So please do not change existing action names without very strong reasons to do so.
#* The same point applies for names of merge points and groups in the ui.rc.
# Syntax highlighting names
#* Similarly, embedding applications may want to set a specific highlighting mode under some circumstances. To do so they will probably use KTextEditor::Document::setHighlightingMode(), which takes the name of the highlighting mode as parameter. Thus, please be very careful when changing names.
# Removing the implementation of KTextEditor Extension interfaces
#* Theoretically, embedding applications may not assume that a certain extension interface (such as KTextEditor::SmartInterface) is implemented by the embedded part. In practice they do. Thus, if you ever have the need to remove a certain interface implementation, be sure you announce this '''very''' visibly, and to allow ample time for embedding applications to adjust to the change.
=== ktexteditor ===
'''This directory is actually part of kdelibs'''. It is synced with kdelibs, regularly, but technically it belongs to kdelibs (at least for KDE 4.x.y). Thus, any changes you do, here, ''must'' follow the kdelibs library code policy: http://techbase.kde.org/Policies/Library_Code_Policy . Before you touch anything, in this directory, please be sure to read and understand that in full. In particular you should have a firm undersanding of API and ABI compatibility issues. '''If in any doubt: Ask'''.
In any case, notify kwrite-devel about changes in that directory.
|
