Docs/Developers/readme-developers.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2   "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5   <title>readme-developers.html</title>
   6   <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
   7   <style type="text/css">
   8   <!--
   9     body {
  10       font-family: Verdana,Helvetica,Arial,sans-serif;
  11       font-size: small;
  12     }
  13     code,pre {
  14       font-family: "Courier New",Courier,monospace;
  15       font-size: 1em;
  16     }
  17     h3 {
  18       padding: 2px;
  19       border-left: 4px solid #FFCC00;
  20       border-bottom: 1px solid #FFCC00;
  21     }
  22     h4 {
  23       padding: 2px;
  24       border-left: 8px solid #FF9933;
  25       border-bottom: 1px solid #FF9933;
  26     }
  27     h5 {
  28       font-size: small;
  29     }
  30     pre {
  31       margin-left: 25px;
  32       margin-right: 25px;
  33       padding: 5px;
  34       background-color: #EEEEEE;
  35       border-left: 10px solid #CCCCCC;
  36     }
  37     p.note {
  38       padding: 5px;
  39       background-color: #DDDDFF;
  40       border: 1px solid #6666FF;
  41     }
  42     acronym {
  43       cursor: help;
  44       border-bottom: 1px dotted black;
  45     }
  46   -->
  47   </style>
  48 </head>
  49 <body>
  50 <h2>readme-developers.html</h2>
  51
  52 <h3>Table of Contents</h3>
  53 <ol>
  54   <li><a href="#Code_changes">Code changes</a></li>
  55   <li><a href="#Minor_code_changes_and_bug_fixes">Minor code changes and bug fixes</a></li>
  56   <li><a href="#Coding_conventions">Coding conventions</a></li>
  57   <li><a href="#Doxygen_comments">Doxygen comments</a></li>
  58   <li><a href="#Revision_Ids">Revision Ids</a></li>
  59   <li><a href="#File_release_numbers">File release numbers</a></li>
  60   <li><a href="#Packaging_file_releases">Packaging file releases</a></li>
  61   <li><a href="#Tagging_SVN_when_releasing_files">Tagging Subversion when releasing files</a></li>
  62   <li><a href="#Localization">Localization</a></li>
  63   <li><a href="#Logging">Logging</a></li>
  64   <li><a href="#ShellExt">Shell Extension</a></li>
  65 </ol>
  66
  67
  68 <h3><a name="Code_changes">Code changes</a></h3>
  69
  70 <p>Please follow these guidelines when submitting changes to WinMerge sources
  71 as patches.</p>
  72
  73 <p class="note">Do not waste yours and our time by submitting large feature
  74 patches before you have made sure the feature is a desired addition to WinMerge. Communicate with
  75 our developers,
  76 either in bug/feature request(rfe) items or preferably in the Developers-forum or Developers-
  77 mailing list.</p>
  78
  79 <ol>
  80   <li><p>Post development intentions:</p>
  81     <ul>
  82       <li>
  83         If you are fixing a bug, put a note in the SourceForge bug report that you're
  84         fixing it. If there is no SourceForge bug report, create one.
  85       </li>
  86       <li>
  87         If you are implementing a new feature, put a note in the SourceForge Feature
  88         Request item that you're implementing it. If there is no SourceForge Feature
  89                 Request item, create one. Alternatively you can discuss new features
  90                 in the Developers-forum or Developers-mailing list. Please use this! It is a lot
  91                 less work wasted when we agree about design first.
  92       </li>
  93     </ul>
  94   </li>
  95   <li>
  96     <p>Before you start developing, make sure to capture
  97     a snapshot of your starting sources (presumably a pristine copy of sources from
  98     subversion, or of a source zip from a distribution).</p>
  99
 100     <p><b>DO NOT</b> submit a patch against a year-old version. The latest experimental/beta version
 101     is at most a few weeks old. Stable releases should only get bug fixes. And even then
 102     the bugfix
 103     is usually first applied to development versions. So there should be no reason to submit
 104     a patch against an old version.</p>
 105   </li>
 106   <li>
 107     <p>Review the sections on <a href="#Coding_conventions">Coding conventions</a>
 108     and <a href="#Doxygen_comments">Doxygen comments</a></p>
 109   </li>
 110   <li><p>Develop your new version.</p></li>
 111   <li>
 112     <p>Post your changes as a patch, to the SourceForge patch list. Try to give an
 113     informative patch title of course. Post to any relevant SourceForge bugs
 114     or RFEs, giving the patch number and title.</p>
 115     <p>If the bug/rfe item is already assigned to you (or you submitted it), you can
 116     also attach patch into that item. Remember to add a comment so others notice the
 117     new attachment.</p>
 118     <p>The active developers have often been posting entire original and modified
 119     files rather than traditional diffs, because obviously all developers
 120     have access to WinMerge to compare original and modified files, and this
 121     may be viewed as an infinite line context diff :)</p>
 122     <p><b>HINT:</b> If you have archive support installed in WinMerge you can do a folder
 123     compare of your original and changed source trees. And then select <code>Zip - Differences</code>
 124     from context menu and WinMerge creates a zip-file for you. Ready to be posted!</p>
 125   </li>
 126   <li>
 127     <p>Wait for reactions from other developers (and sometimes active users).<br>
 128     Usually this means one of the active developers approves your patch before
 129     you commit.</p>
 130   </li>
 131   <li>
 132     <p>After a reasonable amount of time has passed, and one of active developers
 133     has approved the patch, apply the patch to Subversion. (Or ask a
 134     project member to do so, if you don't have developer access to
 135     the project.)</p>
 136     <p>What is a reasonable amount of time? That is somewhat subjective, and
 137     we need to rely on your expertise as the patch developer, but let us
 138     suggest waiting a few days for minor patches, and at least a week for
 139     major patches.</p>
 140   </li>
 141   <li>
 142     <p>Add a note in <code>Src/Changes.txt</code> telling what files you committed,
 143     and what bug/RFE/patch you solved. This is very important so everybody else
 144     has a chance to figure out who did what and when.</p>
 145   </li>
 146 </ol>
 147
 148 <p>Note that <code>Src/Changes.txt</code> was split from <code>Src/readme.txt</code> after
 149 2.4.0 release. So <code>Src/readme.txt</code> contains older changelog entries. Also, many
 150 subfolders have their own <code>Changes.txt</code> -file. If the file exists in the folder, it must be
 151 used instead of "global" <code>Src/Changes.txt</code>.
 152
 153 <h3><a name="Minor_code_changes_and_bug_fixes">Minor code changes and bug fixes</a></h3>
 154
 155 <p>It is reasonable to post small snippets of code showing small changes
 156 directly in the text in bug postings, or patch postings. For example, see
 157 <a href="http://sourceforge.net/tracker/?group_id=13216&amp;atid=313216&amp;func=detail&amp;aid=824987">PATCH [ 824987 ] "Change binary-file detection (look only for zeros)"</a>,
 158 which gives the change directly in the text.</p>
 159
 160 <p>Note, however, that sourceforge trackers currently ignore tabs, so if you
 161 can convert tabs to spaces in your posting, it helps greatly.</p>
 162
 163 <p>Bugfixes may be treated less formally, especially for simple ones, or for
 164 fixes to code you know well -- eg, you caused the bug yourself with a
 165 recent patch :)</p>
 166
 167 <p>Consider still posting something to the tracker lists, even if it is
 168 simply a summary in English. If the fix is something like
 169 "misspelled variable name foo as fooz in many places", it is quite
 170 understandable that you prefer to just fix the instances rather than
 171 doing a full patch for it.</p>
 172
 173 <h3><a name="Coding_conventions">Coding conventions</a></h3>
 174
 175 <p>Please conform to the prevalent coding conventions. There are quite a number of
 176 files which originated elsewhere, and have their own coding conventions; please
 177 conform to the local one, in whichever files you are at work.</p>
 178
 179 <ol>
 180   <li>
 181     <p>WinMerge itself uses Microsoft MFC style coding.</p>
 182     <ul>
 183       <li>Code indents are purely tabs.</li>
 184       <li>
 185         Curly braces are on their own line, indented at the level of the outer code, and
 186         code inside the braces is indented one further level.
 187       </li>
 188       <li>Class member variables are usually prefixed with <code>m_</code>.</li>
 189     </ul>
 190   </li>
 191   <li>
 192     <p>Crystal Text Editor (<code>WinMerge/editlib/*</code>) and diffutils code (<code>io.c</code>,
 193     <code>normal.c</code>, <code>util.c</code>) use traditional Unix style coding.
 194     <code>analyze.c</code> should be in this format, but we have made a mess of it :(</p>
 195     <ul>
 196       <li>Code indents are spaces, with tabs used to abbreviate eight consecutive spaces.</li>
 197       <li>
 198         Curly braces are on their own line, indented two spaces, and then the code inside
 199         the curly braces is indented an additional two spaces.
 200       </li>
 201     </ul>
 202   </li>
 203 </ol>
 204
 205 <h3><a name="Doxygen_comments">Doxygen comments</a></h3>
 206
 207 <p>We have adopted <a href="http://www.doxygen.org">doxygen</a> style as our desired
 208 commenting style for functions, classes, files, and so forth, in WinMerge code
 209 (this applies only to native WinMerge code, not imported files).</p>
 210
 211 <ul>
 212   <li>We're using JavaDoc style comments.</li>
 213   <li>
 214     It is probably easiest to simply imitate existing examples. The functions in
 215     <code>DiffThread.cpp</code> are fully doxygen commented (<em>TODO: it would be better to give a
 216     class example, if anyone knows a fully doxygen commented class</em>).
 217   </li>
 218   <li>There is ready to use doxygen config file in <code>docs/developers/doxygen.cfg</code></li>
 219 </ul>
 220
 221 <h3><a name="Revision_Ids">Revision IDs</a></h3>
 222
 223 <p>We have adopted the convention of using Revision ID lines near the top of our source
 224 files (following the doxygen file header comments). Merely add these two lines
 225 to any new file you add to the repository, and SVN will modify the Id line by
 226 appending revision and date information at checkout:</p>
 227
 228 <pre>
 229 // Revision ID line follows -- this is updated by SVN
 230 // &#36;Id&#36;
 231 </pre>
 232
 233 <h3><a name="File_release_numbers">File release numbers</a></h3>
 234
 235 <p>We are trying to keep a consistent numbering scheme on our file releases,
 236 so everybody can figure out what we have released by just looking at the
 237 release number. Unfortunately the original 4-number version numbering didn't
 238 work as well as we thought and caused a lot of confusion. So WinMerge 2.13.x
 239 and later use new 3-number version numbers:</p>
 240
 241 <pre>
 242 2.14.2
 243 |  | |
 244 |  | |
 245 |  | |
 246 |  | `--------- Denotes a beta release, an experimental release
 247 |  |             or a minor bug fix of a major release.
 248 |  |             For experimental and stable releases this number increases by
 249 |  |             one. For beta releases we may increase few numbers more.
 250 |  `----------- Denotes a major release.
 251 |                even numbers means "stable".
 252 |                odd numbers means "unstable".
 253 `------------- Denotes a major release with major changes.
 254 </pre>
 255
 256 <p>In this case:</p>
 257 <ul>
 258   <li>The next experimental release will have the number 2.15.1 (and then
 259     2.15.2 and then 2.15.3 and so on)</li>
 260   <li>The next beta release will likely have the number 2.15.10 or 2.15.20</li>
 261   <li>The next major release will have the number 2.16.0</li>
 262 </ul>
 263
 264 <p>And if we decide to rewrite most of the code, the next major release will
 265 have the number 3.0.0. This is something big like cross-platform support, 3-way
 266 merge etc.</p>
 267
 268 <p>WinMerge 2.12.x and earlier releases used a four-number version numbers:
 269
 270 <pre>
 271 2.1.2.0
 272 | | | |
 273 | | | `------- This number increases for each experimental,
 274 | | |          and it is reset after each beta or major release.
 275 | | `--------- Denotes a beta release, an experimental release
 276 | |            or a minor bug fix of a major release.
 277 | |              even numbers means "stable" (i.e. a beta).
 278 | |              odd numbers means "unstable" (i.e. an experimental).
 279 | `----------- Denotes a major release.
 280 |                even numbers means "stable".
 281 |                odd numbers means "unstable".
 282 `------------- Denotes a major release with major changes.
 283 </pre>
 284
 285 <h3><a name="Packaging_file_releases">Packaging file releases</a></h3>
 286
 287 <p>On SourceForge there is some space to enter Release Notes and Change Notes.
 288 For experimental releases make sure to put in a note telling people that this is indeed experimental,
 289 so they should not expect everything to work perfectly.
 290 For beta builds we paste in all the changes since the last beta release, so that people can see exactly what changed.
 291 For major releases, we paste in the list of changes since the last major release, and this list can become very long.</p>
 292
 293 <p>We are using <a href="http://www.jrsoftware.org/isinfo.php">InnoSetup</a> to make
 294 the installer for WinMerge.
 295 See <a href="readme-developers-InnoSetup.html">readme-developers-InnoSetup.html</a> for more information.
 296 Also zip-packages for releases are provided, zip up these files:</p>
 297
 298 <ul>
 299   <li><code>WinMerge.exe</code> and <code>WinMergeU.exe</code></li>
 300   <li><code>ShellExtension.dll</code>, <code>ShellExtensionU.dll</code>, <code>register.bat</code>
 301   and <code>unregister.bat</code> to register/unregister it.</li>
 302   <li>All filters from the <code>filters/</code> directory (remember template file!)</li>
 303   <li>All plugins from the <code>plugins/dlls/</code> directory. Create a <code>MergePlugins/</code> directory and copy the plugins to it</li>
 304   <li>All <code>*.lang</code> files (currently we have 21 languages, counting both Chinese versions)</li>
 305 </ul>
 306
 307 <p>Please remember to put the version number into both executables. You may use
 308 any of the following three methods at least.</p>
 309 <ol>
 310  <li>
 311  You may run Src/SetResourceVersions.bat, which will prompt for the new
 312  version number, and set it both in Merge.rc and in all the translated rc files.
 313  </li><li>
 314  You may use
 315  <a href="http://www.elphin.com/products/stampver.html">StampVer</a> to stamp
 316  the version number into the executables after they are compiled.
 317  </li><li>
 318  You may also use the old-fashioned process
 319  of simply copying all the sources, changing the <code>Merge.rc</code> in the copy using
 320  the MSVC6 resource editor, and compiling that (many releases have been made in this
 321  manual, low-tech fashion).
 322  </li>
 323 </ol>
 324 <p>Whatever method you use, please double-check the
 325 executable version numbers before uploading and releasing them.</p>
 326
 327 <p>
 328   Since WinMerge 2.4 we have translations for Shell Extension and must also version it
 329   carefully. If we don't update version number, installer won't install updated version.
 330   There are no scripts or other tools to update version number, it must be done by hand
 331   to <code>ShellExtension.rc</code> file (make sure you update all four numbers!). Version numbers
 332   follow the rule:
 333 </p>
 334 <pre>
 335 1.6.1.0
 336 | | | |
 337 | | | `------- Not used - 0 (or your own build version?)
 338 | | `--------- Translation updates or other minor changes increase this by one
 339 | `----------- New features, bug fixes and other changes affecting to behavior
 340 |                increase this number by one
 341 `------------- Denotes a major release with major changes.
 342 </pre>
 343 <ul>
 344   <li>Make sure that version number is updated every time you do a new release!</li>
 345   <li>If there are only small changes not affecting behaviour or translation updates<br>
 346     - increase 3rd number by one</li>
 347   <li>If there's been new features, bug fixes or other non-minor changes<br>
 348     - increase 2nd number by one</li>
 349 </ul>
 350
 351 <p>Filenames in file releases follow this standard:</p>
 352 <ul>
 353   <li><code>WinMerge-2.1.6.0-exe.zip</code></li>
 354   <li><code>WinMerge-2.1.6.0-src.zip</code></li>
 355   <li><code>WinMerge-2.1.6.0-Setup.exe</code></li>
 356 </ul>
 357
 358 <p>That is, dots are used only inside the version number and before the final extension.</p>
 359
 360 <h3><a name="Tagging_SVN_when_releasing_files">Tagging Subversion when releasing files</a></h3>
 361
 362 <p>When we make a release we always put a note in <code>Src/Changes.txt</code> in SVN.</p>
 363
 364 <p>It is recommended to create a tag to the repository when making a stable- or beta- releases.
 365 Although with subversion we have kind of tags for every commit (revision numbers) it is still a lot
 366 easier to handle and remember them with human-readable names (R2_6_0) than with revision numbers
 367 (revision 3637 (not a real revision number!)). Experimental or other testing releases don't need
 368 tags since they are not intended for wide use and are usually just one-time snapshots.</p>
 369
 370 <p>The tag should follow the same numbering scheme as used above, with the dots replaced by underscores
 371 and prefixed with an <code>R</code>, so the example experimental above would have a tag named <code>R2_1_3_0</code>,
 372 the next beta would be named <code>R2_1_4</code>, and the next major release would be named <code>R2_2</code>.</p>
 373
 374 <h3><a name="Localization">Localization</a></h3>
 375
 376 <p><code>WinMerge.exe</code> and <code>WinMergeU.exe</code> are always compiled with the english resources.
 377 Custom languages are in per-language PO files in <code>Languages</code> subfolder of WinMerge folder.
 378 Language may be changed dynamically through the menu.</p>
 379
 380 <p>WinMerge localization is achieved by loading translated strings from per-language PO files. There is only one rc
 381 file in the project <code>Merge.rc</code>, which is used to generate  POT (PO template) file. Per-language PO files
 382 are updated (after <code>Merge.rc</code> changes) from generated POT file. All PO files are in same
 383 <code>Languages</code> subfolder.
 384
 385 <p>Unlike with 2.6.x versions of WinMerge, there is no anymore need to compile language files. The same PO files
 386 are used for translation and in runtime to load translated strings. This helps translating WinMerge a lot.
 387
 388 <p>If you have done changes to the <code>Merge.rc</code> file you must call <code>UpdateTranslations.bat</code>
 389 to create the latest version from the file <code>English.pot</code> and update the language PO files from this PO template.
 390 And for strings, who should not appear in the PO files just add a line in the <code>Languages/StringBlacklist.txt</code> file.</p>
 391
 392 <p class="note">Besides the resources files you could also translate things like the
 393 <a href="http://svn.sourceforge.net/viewvc/winmerge/trunk/WinMerge/InnoSetup/Languages/">installer</a>
 394 (the ISL files are just INI files) and the <a href="http://svn.sourceforge.net/viewvc/winmerge/trunk/WinMerge/Docs/Users/Languages/">readme files</a>.</p>
 395
 396 <h4>Tips for developers :</h4>
 397 <ul>
 398   <li><p>The code must use resource strings for all messages, or displayed text (column title ...).</p></li>
 399   <li>
 400     <p><strong>Strings ID</strong>: when applying a patch, you may define new strings (with as ID the first free ID).
 401     But probably you wrote your patch from an old version, and someone may have already inserted a patch for this ID.
 402     You need to adapt the ID in resource.h to avoid overlapping ID.</p>
 403   </li>
 404   <li>
 405     <p><strong>Strings order</strong>: that is really annoying with MSVC. It is important to keep the order of strings unchanged,
 406     because merging rc files with WinMerge is then a lot easier. Strings are grouped in block according to their ID masked by <code>0xFFF0</code>.
 407     So there are at most 16 strings in a block, but maybe less. MSVC reorders strings between and inside blocks, but never reorders blocks
 408     (when a new blocks is created, MSVC always put it at the last position).</p>
 409     <p>Typical method to merge strings in a <code>Merge.rc</code> from a patch with a <code>Merge.rc</code> in SVN :</p>
 410     <ol>
 411       <li>Add your new strings with WinMerge : <code>resource.h</code> for ID, and <code>Merge.rc</code>.</li>
 412       <li>If no overlapping ID, you are finished.</li>
 413       <li>Update your ID in <code>resource.h</code>.</li>
 414       <li>
 415         Open your resource file in MSVC. Force compilation (I just change a string twice, add a space, delete this space,
 416         then save). So MSVC classes new strings in blocks (possibly creating new blocks) according to the ID updated in 3.
 417       </li>
 418     </ol>
 419     <p><b>Note:</b> Blocks are not really ordered (there order comes from history), it is not a problem as MSVC never reorders
 420     blocks after creation. If you use another tool to change resources, please make sure that the blocks order is unchanged.</p>
 421   </li>
 422 </ul>
 423
 424 <h3><a name="Logging">Logging</a></h3>
 425
 426 <p>Logs are a good tool for tracing errors. But logs must be first written. Its always
 427 a good habit to write error message to logfile also.</p>
 428
 429 <h4>Writing to log:</h4>
 430 <p>Simplest way to write errormessage to log is using
 431 <code>void LogErrorString(LPCTSTR sz)</code> defined in <code>stdafx.h</code>. Another
 432 way is to directly use <code>gLog</code> which is global instance of
 433 <code>CLogFile</code>. Log is written to users temporary directory (<code>$temp</code>) with name
 434 <code>WinMerge.log</code>.</p>
 435
 436 <h4>Enabling/disabling log writing</h4>
 437 <p>Log writing is controlled by registry value:</p>
 438 <pre>HKEY_CURRENT_USER\Software\Thingamahoochie\WinMerge\Settings\Logging</pre>
 439
 440 <p>Possible values are:</p>
 441 <ul>
 442   <li>0 - no logging</li>
 443   <li>1 - all logging enabled</li>
 444   <li>2 - only errormessages and warnings written to log</li>
 445 </ul>
 446
 447 <h3><a name="ShellExt">Shell Extension</a></h3>
 448
 449 <p>WinMerge sets executable path (<code>WinMerge.exe</code>) which shellextension starts every
 450 time when options-dialog is closed. This can cause problems when testing
 451 several versions of WinMerge. There is registry value to overwrite path to
 452 WinMerge executable:</p>
 453
 454 <pre>HKEY_CURRENT_USER\Software\Thingamahoochie\WinMerge\PriExecutable</pre>
 455
 456 <p>It does not exist by default, so create <code>PriExecutable</code> as string value and type
 457 path of <code>WinMerge.exe</code> you mainly use as its value. If this value exists
 458 ShellExtension does not care about another path value.</p>
 459
 460 </body>
 461 </html>