kmail/HACKING

   1 Getting Involved
   2 ================
   3
   4 If you want to code on KMail - don't be shy, just start hacking and send in patches!
   5 You can find easy things to begin with on the techbase wiki, which has a list of KMail
   6 junior jobs: http://techbase.kde.org/Projects/PIM/KMail_Junior_Jobs
   7
   8 See the "Committing" section on how to send patches.
   9
  10 Some starting points are:
  11
  12 General information about contributing to KDE:
  13 http://techbase.kde.org/Contribute
  14
  15 Building KDE:
  16 http://techbase.kde.org/Getting_Started/Build/KDE4
  17 If you want to hack on KMail, you'll first need to set up a build environemnt, which is
  18 described here.
  19
  20 Generally, you just need to set up your build environment, modify the code and then send patches.
  21 The best thing is probably to scratch an itch of yours, e.g. fixing a bug that is annoying you
  22 or writing a feature that you are interested in.
  23 Have a look at bugs.kde.org to see the current KMail bugs and wishes (although some entries on the
  24 bug tracker are outdated).
  25 For working on KMail, some C++ knowledge is required. Qt, KDE and KMail knowledge can probably be
  26 picked up by reading code on experimenting with it (and by reading the documentation, of course!).
  27
  28 Communication
  29 =============
  30
  31 If you need help, have questions or patches, come to the #kontact IRC channel or write to the KDE PIM mailinglist.
  32 You can also write to the maintainer directly.
  33 No questions are too stupid to ask, but make sure you read some of the pages linked from this document.
  34
  35 Documentation
  36 =============
  37
  38 The KMail documentation can be found at http://api.kde.org/4.x-api/kdepim-apidocs/kmail/html/index.html.
  39 The documentation is auto-generated from comments in the KMail code.
  40 Note that many classes are not documented or the documentation is outdated. You'll have to read the code
  41 in order to understand it in those cases.
  42
  43 The file kmail.antispamrc-HOWTO contains information about supporting new types of spam filtering programs.
  44
  45 See techbase.kde.org for many other KDE related developer documentation and tutorials.
  46
  47 Some related RFCs are (see http://www.faqs.org/rfcs/):
  48 RFC4155 - The application/mbox Media Type
  49 RFC2822 - Internet Message Format
  50 RFC2045-2049 - Multipurpose Internet Mail Extensions (MIME)
  51 RFC2183 - Communicating Presentation Information in Internet Messages
  52 RFC2231 - MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations
  53 RFC1847 - Security Multiparts for MIME: Multipart/Signed and Multipart/Encrypted
  54 RFC2633 - S/MIME Version 3 Message Specification
  55 RFC3156 - MIME Security with OpenPGP
  56 RFC2298 - An Extensible Message Format for Message Disposition Notifications
  57 RFC2557 - MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)
  58 RFC1939 - Post Office Protocol - Version 3
  59 RFC1734 - POP3 AUTHentication command
  60 RFC2449 - POP3 Extension Mechanism
  61 RFC2821 - Simple Mail Transfer Protocol
  62 RFC1869 - SMTP Service Extensions
  63 RFC1870 - SMTP Service Extension for Message Size Declaration
  64 RFC2554 - SMTP Service Extension for Authentication
  65 RFC2920 - SMTP Service Extension for Command Pipelining
  66 RFC3501 - INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
  67
  68 The above list is incomplete. Some of those technologies are implemented in kdepimlibs, not in KMail itself.
  69
  70 Branches
  71 ========
  72
  73 KMail has several branches in the following locations:
  74
  75 1. trunk ( trunk/KDE/kdepim/kmail )
  76 This is where the main development takes place. It will be released together with the next major KDE release (KDE 4.x.0)
  77 Patches should be always made against this branch.
  78
  79 2. the stable branch for KDE 4 ( branches/KDE/4.x/kdepim/kmail )
  80 Important bugfixes from trunk should also go to the stable branch, it will be released together with the next minor
  81 KDE release (KDE 4.x.y).
  82
  83 3. the enterprise branch for KDE 4 ( branches/kdepim/enterprise4/kdepim/kmail )
  84 The KMail version in here is part of the official Kolab client, see http://www.kolab.org/.
  85 Changes in this branch are regularly merged to trunk, and changes in the stable branch are regularly merged to here.
  86 This branch is necessary because the Kolab project has a different release cycle than KDE. For example, new features
  87 in trunk are not wanted in this branch for stability reasons. Also, the KDE freezes (feature freeze, string freeze etc)
  88 do not apply to this branch.
  89
  90 4. the enterprise branch for KDE 3.5 ( branches/kdepim/enterprise/kdepim/kmail )
  91 The enterprise branch for the KDE 3.5 Kolab client, similar to the enterprise branch for KDE 4.
  92
  93 5. the enterprise branch for KDE 3.3 ( branches/kdepim/proko2/kdepim/kmail )
  94 This is an even older enterprise branch, against KDE 3.3.
  95
  96 6. The stable branch for KDE 3 ( branches/KDE/3.5/kdepim/kmail )
  97 This is the stable version of KMail for KDE 3. It will be released together with the next minor KDE release of
  98 KDE 3 (KDE 3.5.x).
  99
 100 Committing
 101 ==========
 102
 103 Before you commit (or send a patch)
 104 - Make sure it compiles
 105 - Review the output of svn diff to avoid committing unwanted changes
 106 - Test your changes
 107 - Make sure the coding style is correct
 108
 109 Patches should always be against the current SVN trunk (see below for a list of branches).
 110
 111 If you don't have commit access, add the patch (output of svn diff) to reviewboard.kde.org, to
 112 the KDEPIM group.
 113 You might also be interested in joining the KDE PIM mailinglist,
 114 see http://mail.kde.org/mailman/listinfo/kde-pim.
 115 If you send mail to the list and are not subscribed, please tell that in the mail so we can CC you.
 116
 117 Larger changes, for example new features, should be reviewed first, even if you have commit access.
 118
 119 Try to backport bugfixes to the stable branch. Crash fixes should be always backported.
 120
 121 Follow the other KDE polices in http://techbase.kde.org/Policies/SVN_Commit_Policy.
 122
 123 If ever any argument or conflict should arise over a commit, the following applies (taken from the old
 124 COMMITPOLICY document):
 125 "In the result of a conflict over a commit to the KMail section of KDE SVN
 126  a resolution to this conflict, that is the decision to keep or revert the
 127  commit can be decided by a unanimous agreement of the maintainers, or
 128  failing that a resolution to the conflict will be decided by a vote of KMail
 129  core developers."
 130
 131 Coding Style and other polices
 132 ==============================
 133
 134 KMail is more than 10 years old, and has inconsistent coding style in many places.
 135 However, new code should obey to the standard KMail coding style, to keep things as consistent as possible.
 136
 137 Please don't mix commits that change the coding style of existing code to the standard coding style with other changes.
 138 So when committing coding style fixes, the commit should not change anything else. You can use the SVN_SILENT keyword then.
 139
 140 In short, KMail follows the KDE coding style (http://techbase.kde.org/Policies/Kdelibs_Coding_Style) with some exceptions,
 141 mentioned below.
 142 Note that most of the rest of KDE PIM also follows the KMail style. You should also read the coding style document for
 143 Kontact, which can be found at http://websvn.kde.org/*checkout*/trunk/KDE/kdepim/kontact/HACKING. All of it also applies to
 144 KMail.
 145
 146 Please don't argue against this style, we're stuck with that anyway (changing the style to something else would mess
 147 up the svn annotate function)
 148
 149 So the differences between the KDE coding style and the KMail coding style are:
 150 (the list also contains other things that came into my mind)
 151
 152 - Indentation with 2 spaces instead of 4 spaces
 153
 154 - More spaces at the inside of parenthesis and around operators, e.g.
 155
 156         if ( foo( 2 + 3, 1.0f ) && !blah )
 157           bar( 3 );
 158
 159         instead of
 160
 161         if (foo(2+3, 1.0f) && !blah)
 162           bar(3);
 163
 164   Note that there is no space between the function name and the opening brace, but there is a space between the if and the
 165   opening brace.
 166
 167 - No #defines, except for include guards or conditional compiling.
 168   Use real constants, inline functions and template functions instead.
 169
 170 - Use descriptive variable and function names, try to avoid abbreviating or even using single letter variables.
 171   Code with descriptive names is so much easier to read.
 172
 173 - Don't use the "KM" prefix for new classes anymore, put the class into the "KMail" namespace instead.
 174
 175 - No trailing spaces.
 176
 177 - A debug area for kDebug() and kWarning() calls is no longer needed, it is added by default.
 178
 179 - Avoid long lines. Especially, when the line gets to long because of an added comment, place that comment in its own
 180   line in front of the current line.
 181
 182 - New files must have a license header.
 183
 184 - Use KConfigXT for new global settings (see kmail.kcfg) whenever possible.
 185
 186 - When changing the way config data is stored, you need to make sure older config files can still be read.
 187   For this, write a kconfig update script, see the kconf_update directory for examples.
 188   http://techbase.kde.org/Development/Tools/Using_kconf_update has documentation for this.
 189
 190 Closing
 191 =======
 192
 193 If you think this document is missing anything, tell us about it so we can add it!