README.developer

Code
Comments
Other
Rev Date Author Line
84 13 Mar 06 jari 1 $Id$
26 05 Jan 06 jari 2
338 19 May 07 peter 3 = Developer Information =
338 19 May 07 peter 4
338 19 May 07 peter 5 This file contains developer specific information.
338 19 May 07 peter 6
394 25 Jun 07 jari 7
394 25 Jun 07 jari 8 === Coding style ===
394 25 Jun 07 jari 9
394 25 Jun 07 jari 10 Developers should follow the coding style outlined in the
560 04 Mar 08 peter 11 [http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/index.html C++ coding guidelines].
394 25 Jun 07 jari 12
394 25 Jun 07 jari 13
394 25 Jun 07 jari 14 === Subversion usage ===
394 25 Jun 07 jari 15
394 25 Jun 07 jari 16 Commits should be minimalistic and the projects should always compile
1495 27 Aug 12 peter 17 ('make' and 'make check') when someone makes a clean checkout. There is
394 25 Jun 07 jari 18 a short introduction to subversion and its usage available as
560 04 Mar 08 peter 19 [http://cbbp.thep.lu.se/~jari/documents/subversion_guidelines/index.html Subversion guidelines].
394 25 Jun 07 jari 20 We follow these guidelines.
394 25 Jun 07 jari 21
394 25 Jun 07 jari 22
724 09 Dec 08 peter 23 === Requirements ===
724 09 Dec 08 peter 24
724 09 Dec 08 peter 25 To build from a subversion checkout, you will need Autotools. More
1299 14 Nov 10 peter 26 specifically Automake 1.11 (or later) and Autoconf 2.63 (or later). To
724 09 Dec 08 peter 27 build man page you will need help2man.
724 09 Dec 08 peter 28
1495 27 Aug 12 peter 29 === bootstrap and autoreconf ===
387 24 Jun 07 jari 30
481 09 Oct 07 jari 31 At first checkout from the repository you must run the bootstrapping
481 09 Oct 07 jari 32 utility
338 19 May 07 peter 33
1495 27 Aug 12 peter 34   #> ./bootstrap
338 19 May 07 peter 35
338 19 May 07 peter 36
338 19 May 07 peter 37 === configure ===
338 19 May 07 peter 38
1495 27 Aug 12 peter 39 Run the generated configure script with
387 24 Jun 07 jari 40
1495 27 Aug 12 peter 41   #> ./configure --enable-debug
338 19 May 07 peter 42
1495 27 Aug 12 peter 43 The option flag '--enable-debug' turns on some compiler options
1495 27 Aug 12 peter 44 appropriate for development (e.g. enables assertions).
338 19 May 07 peter 45
394 25 Jun 07 jari 46
394 25 Jun 07 jari 47 === Testing ===
394 25 Jun 07 jari 48
1495 27 Aug 12 peter 49 Test programs should be created and added to the 'make check'
394 25 Jun 07 jari 50 execution. Always check that the test runs before committing code to
1495 27 Aug 12 peter 51 the repository, i.e., run 'make check'. For more details on how to run
1495 27 Aug 12 peter 52 and write tests, please refer to file 'test/README'.
394 25 Jun 07 jari 53
1495 27 Aug 12 peter 54 There is a test repository in 'test/repo' that is a part of
394 25 Jun 07 jari 55 the svndigest repository. The logic behind this is that it is nice to
394 25 Jun 07 jari 56 have a common test repository that can be used off-line. Changes to
394 25 Jun 07 jari 57 the repository are usually made to create new test cases and it is
394 25 Jun 07 jari 58 important that these changes are committed to svndigest repository as
394 25 Jun 07 jari 59 well. All changes to the test repository are not automatically
394 25 Jun 07 jari 60 propagated to the svndigest repository and it is important that some
394 25 Jun 07 jari 61 files created in the test repository are manually added to the
1495 27 Aug 12 peter 62 svndigest repository. Assuming that 'make check' is run before a
394 25 Jun 07 jari 63 commit, a warning is generated if the test repository is inconsistent
394 25 Jun 07 jari 64 with the svndigest repository. There will be a diagnostic message and
394 25 Jun 07 jari 65 a resolution hint, however the developer must examine and resolve the
394 25 Jun 07 jari 66 problem manually.
394 25 Jun 07 jari 67
1495 27 Aug 12 peter 68 The problem is simply that the file 'test/repo/db/current'
1495 27 Aug 12 peter 69 is changed compared to the svndigest repository. The 'current' file
394 25 Jun 07 jari 70 indicates a specific number of change sets within the test repository
1495 27 Aug 12 peter 71 and the directories 'test/repo/db/revs' and
1495 27 Aug 12 peter 72 'test/repo/db/revprops' contains a matching number of
394 25 Jun 07 jari 73 change sets. However, the change sets added to the test repository are
394 25 Jun 07 jari 74 not automatically added to the svndigest repository, therefore the new
1495 27 Aug 12 peter 75 files in the 'revs' and 'revprops' directories must be added manually
394 25 Jun 07 jari 76 to the svndigest repository.
394 25 Jun 07 jari 77
394 25 Jun 07 jari 78 There is also a race condition when developers make changes to the
394 25 Jun 07 jari 79 test repository simultaneously: It is easy to create severe conflicts
583 11 Apr 08 peter 80 in the test repository. Imaging the case when two developers add test
394 25 Jun 07 jari 81 commits to the test repository, and then tries to add these to the
394 25 Jun 07 jari 82 svndigest repository. Since there are different versions of the same
394 25 Jun 07 jari 83 test repository revisions, the second developer committing to the
394 25 Jun 07 jari 84 svndigest will get messages about files being in the way. This is just
394 25 Jun 07 jari 85 one situation with possible conflicts. This conflict is of course
394 25 Jun 07 jari 86 resolved by the second developer having to throw away his changes and
394 25 Jun 07 jari 87 redo them after a new checkout of the test repository.
394 25 Jun 07 jari 88
394 25 Jun 07 jari 89 The take home message is that developers should communicate with each
394 25 Jun 07 jari 90 other when changing the test repository in order to avoid to large
1495 27 Aug 12 peter 91 repository conflicts. AND read the output of 'make check'.
394 25 Jun 07 jari 92
394 25 Jun 07 jari 93
825 26 Sep 09 peter 94 === yat library ===
825 26 Sep 09 peter 95
1495 27 Aug 12 peter 96 Directory 'yat/' contains some files from the yat library. These
825 26 Sep 09 peter 97 files are not owned by svndigest and should not (if possible) be
1495 27 Aug 12 peter 98 edited here. For more details please see 'yat/README'.
825 26 Sep 09 peter 99
494 14 Oct 07 peter 100 === Output file structure ===
494 14 Oct 07 peter 101
494 14 Oct 07 peter 102 A directory reflecting the parsed directory is generated for each
494 14 Oct 07 peter 103 combination of StatsType, Author, and LineType, which is located in
1495 27 Aug 12 peter 104 '<TARGET>/<ROOT>/StatsType/Author/LineType/'. Author may be, on top of
1495 27 Aug 12 peter 105 each author in the repository, a directory 'all' that is a sum over
1495 27 Aug 12 peter 106 all authors. In same fashion 'LineType' may be any of the three
1495 27 Aug 12 peter 107 linetypes but may also be 'total', which is a sum over all
1495 27 Aug 12 peter 108 linetypes. In each '<TARGET>/<ROOT>/StatsType' there are directories
1495 27 Aug 12 peter 109 'images/LineType' that contain a structure reflecting the parsed
1495 27 Aug 12 peter 110 directory with images for every combination of 'File', 'LineType', and
1495 27 Aug 12 peter 111 'StatsType'. Images for different authors are identical and therefore
496 14 Oct 07 peter 112 shared between authors.
494 14 Oct 07 peter 113
874 22 Nov 09 peter 114 == Design and Motivation ==
494 14 Oct 07 peter 115
1495 27 Aug 12 peter 116 Please refer to 'doc/HACKING' for a list of design decisions we try to
1495 27 Aug 12 peter 117 follow.
874 22 Nov 09 peter 118
1495 27 Aug 12 peter 119 = Releasing =
338 19 May 07 peter 120
1495 27 Aug 12 peter 121 The main development is performed in the trunk branch of the
1495 27 Aug 12 peter 122 repository. A new release branch is created for each minor release
1495 27 Aug 12 peter 123 from the trunk and patch releases are snapshots of the minor release
1495 27 Aug 12 peter 124 branch. This implies that patch work is performed in the minor release
1495 27 Aug 12 peter 125 branch, and changes made release branch is transferred to the trunk
1495 27 Aug 12 peter 126 every time a new patch release is made. Remember, patch work should be
1495 27 Aug 12 peter 127 limited to bug fixes and important fixes only leaving development of
1495 27 Aug 12 peter 128 new features and designs to the trunk branch.
394 25 Jun 07 jari 129
1495 27 Aug 12 peter 130 Releases should only be performed by an appointed member of the team,
1495 27 Aug 12 peter 131 the Release Manager.
394 25 Jun 07 jari 132
1495 27 Aug 12 peter 133 == Release procedure ==
1495 27 Aug 12 peter 134
1495 27 Aug 12 peter 135 This section describes what to do when publishing a release.
1495 27 Aug 12 peter 136
1495 27 Aug 12 peter 137 === Creating a release branch ===
1495 27 Aug 12 peter 138
1495 27 Aug 12 peter 139 Once people agree that a new release branch should be made, the
1495 27 Aug 12 peter 140 Release Manager creates it with the following procedure (substitute
1495 27 Aug 12 peter 141 A.B with the version you are preparing):
1495 27 Aug 12 peter 142
1495 27 Aug 12 peter 143 1. Mark the new minor series in 'NEWS':
1495 27 Aug 12 peter 144
1495 27 Aug 12 peter 145 8<---
1495 27 Aug 12 peter 146  See the end for copyrights and conditions.
1495 27 Aug 12 peter 147
1495 27 Aug 12 peter 148 +svndigest A.B.x series from
1495 27 Aug 12 peter 149 +          http://dev.thep/lu.se/svndigest/svn/branches/A.B-stable
1495 27 Aug 12 peter 150 +
1495 27 Aug 12 peter 151 Version A.B (released NOT YET)
1495 27 Aug 12 peter 152 8<---
1495 27 Aug 12 peter 153
1495 27 Aug 12 peter 154    commit the changes with
1495 27 Aug 12 peter 155
1495 27 Aug 12 peter 156    #> svn ci -m "preparing branch A.B-stable"
1495 27 Aug 12 peter 157
1495 27 Aug 12 peter 158 2. Update copyright statements with commands
1495 27 Aug 12 peter 159
1636 30 Mar 23 peter 160    #> make copyright
1495 27 Aug 12 peter 161
1495 27 Aug 12 peter 162    Examine the updates and commit changes with
1495 27 Aug 12 peter 163
1495 27 Aug 12 peter 164    #> svn ci -m "updating copyright statements"
1495 27 Aug 12 peter 165
1495 27 Aug 12 peter 166 3. Create a new minor branch using a one liner like
1495 27 Aug 12 peter 167
1495 27 Aug 12 peter 168    #> make svn-stable-branch
1495 27 Aug 12 peter 169
1495 27 Aug 12 peter 170 4. Prepare the trunk for the next minor release:
1495 27 Aug 12 peter 171
1495 27 Aug 12 peter 172    a) Update version number in 'm4/version.m4'.
1495 27 Aug 12 peter 173       MY_VERSION_early([A], [B+1], [0], [true])
1495 27 Aug 12 peter 174
1495 27 Aug 12 peter 175    b) Add an entry in 'NEWS'
1495 27 Aug 12 peter 176
1495 27 Aug 12 peter 177 version A.[B+1] (released NOT YET)
1495 27 Aug 12 peter 178
1495 27 Aug 12 peter 179       The date is set when version A.[B+1] is released.
1495 27 Aug 12 peter 180
1495 27 Aug 12 peter 181    c) Commit changes to the repository
1495 27 Aug 12 peter 182
1495 27 Aug 12 peter 183    #> svn ci -m "Bumping VERSION to A.[B+1]"
1495 27 Aug 12 peter 184
1495 27 Aug 12 peter 185
1495 27 Aug 12 peter 186 === Rolling a release ===
1495 27 Aug 12 peter 187
1495 27 Aug 12 peter 188 This section describes how to release a new version. If this is a
1523 28 Sep 12 peter 189 minor release (C=0), replace A.B.C with A.B. Before you start, make
1670 05 Jul 23 peter 190 sure you have write access to sourceforge page, that you have git
1670 05 Jul 23 peter 191 installed, and that you can create checksum files, i.e., you need
1670 05 Jul 23 peter 192 'openssl' and 'md5'/'md5sum'.
1495 27 Aug 12 peter 193
1495 27 Aug 12 peter 194 1. Create a new milestone for next patch release A.B.[C+1].
1495 27 Aug 12 peter 195
1495 27 Aug 12 peter 196 2. Update version number in 'm4/version.m4'. Locate and change the below line
1495 27 Aug 12 peter 197 ---
1495 27 Aug 12 peter 198 MY_VERSION_early([A], [B], [C], [false])
1495 27 Aug 12 peter 199 ---
1495 27 Aug 12 peter 200
1495 27 Aug 12 peter 201 3. Update file 'THANKS'
1495 27 Aug 12 peter 202
1495 27 Aug 12 peter 203 4. Make sure that the items in 'NEWS' cover the new features of the
1495 27 Aug 12 peter 204    release. Set the date for the new release:
1495 27 Aug 12 peter 205
1523 28 Sep 12 peter 206 version A.B.C (released 26 June 2007)
1495 27 Aug 12 peter 207
1495 27 Aug 12 peter 208 5. Commit changes to the repository
1495 27 Aug 12 peter 209
1495 27 Aug 12 peter 210    #> svn ci -m "Preparing release A.B.C"
1495 27 Aug 12 peter 211
1495 27 Aug 12 peter 212 6. Update copyright statements with commands
1495 27 Aug 12 peter 213
1652 14 Jun 23 peter 214    #> make copyright
1495 27 Aug 12 peter 215
1495 27 Aug 12 peter 216    Examine the updates and commit changes with
1495 27 Aug 12 peter 217
1495 27 Aug 12 peter 218    #> svn ci -m "updating copyright statements"
1495 27 Aug 12 peter 219
1495 27 Aug 12 peter 220 7. Issue 'svn update' to make entire wc to be in revision 'HEAD'.
1495 27 Aug 12 peter 221    Needless to say, make sure that the program is in a state to be
1495 27 Aug 12 peter 222    released; make sure that all the tests pass, test the distribution
1495 27 Aug 12 peter 223    package, and perform all other release tests you think is
1495 27 Aug 12 peter 224    appropriate. Run:
1495 27 Aug 12 peter 225
1652 14 Jun 23 peter 226   #> make release-tag-upload
1495 27 Aug 12 peter 227
1495 27 Aug 12 peter 228
1495 27 Aug 12 peter 229 8. Update wiki first page under section 'Latest Release'.
1495 27 Aug 12 peter 230
1495 27 Aug 12 peter 231    a) Update version to A.B.C.
1495 27 Aug 12 peter 232
1495 27 Aug 12 peter 233    b) Update link to NEWS file to 'source:tags/A.B.C/NEWS'
1495 27 Aug 12 peter 234
1495 27 Aug 12 peter 235    c) If this is a minor release (C=0) update links to
1495 27 Aug 12 peter 236       'source:branches/A.B-stable/doc/readme.txt',
1495 27 Aug 12 peter 237       'source:branches/A.B-stable/README'.
1495 27 Aug 12 peter 238
1495 27 Aug 12 peter 239 9. Update SubversionCheckout
1495 27 Aug 12 peter 240
1495 27 Aug 12 peter 241    a) In section 'svndigest latest release' update link to
1495 27 Aug 12 peter 242       [source:tags/A.B.C/NEWS NEWS] and modify the svn commands to
1495 27 Aug 12 peter 243
1495 27 Aug 12 peter 244 svn checkout http://dev.thep.lu.se/svndigest/svn/tags/A.B.C svndigest-A.B.C
1495 27 Aug 12 peter 245
1495 27 Aug 12 peter 246 svn switch http://dev.thep.lu.se/svndigest/svn/tags/A.B.C
1495 27 Aug 12 peter 247
1495 27 Aug 12 peter 248    b) If this is a minor release (C=0) update link in 'svndigest stable' to
1495 27 Aug 12 peter 249       [source:branch/A.B-stable/NEWS NEWS] and modify the svn commands to
1495 27 Aug 12 peter 250
1495 27 Aug 12 peter 251 svn co http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable svndigest-A.B
1495 27 Aug 12 peter 252
1495 27 Aug 12 peter 253 svn switch ^/branches/A.B-stable
1495 27 Aug 12 peter 254
1495 27 Aug 12 peter 255 10. Add a version A.B.C using trac-admin tool
1495 27 Aug 12 peter 256
1495 27 Aug 12 peter 257 11. Close milestone A.B.C
1495 27 Aug 12 peter 258
1495 27 Aug 12 peter 259 12. Merge the release into trunk. Go to a pristine trunk WC and
1495 27 Aug 12 peter 260
1495 27 Aug 12 peter 261    #> cd /path/to/svndigest-trunk
1495 27 Aug 12 peter 262    #> svn update
1495 27 Aug 12 peter 263    #> svn diff
1523 28 Sep 12 peter 264    #> svn merge ^/branches/A.B-stable
1495 27 Aug 12 peter 265
1495 27 Aug 12 peter 266    Resolve all conflicts. Run tests and perform all other appropriate
1495 27 Aug 12 peter 267    tests to make sure that the merge does not create havoc. Typically
1495 27 Aug 12 peter 268    changes in 'm4/version.m4' are problematic so check this file extra
1495 27 Aug 12 peter 269    carefully.
1495 27 Aug 12 peter 270
1495 27 Aug 12 peter 271    Commit changes to the trunk branch.
1495 27 Aug 12 peter 272
1495 27 Aug 12 peter 273    #> svn commit -m "Merged release A.B.C to the trunk."
1495 27 Aug 12 peter 274
1495 27 Aug 12 peter 275 13. Prepare stable branch for future release
1495 27 Aug 12 peter 276
1495 27 Aug 12 peter 277    a) Update version number in 'version.m4' in line
1495 27 Aug 12 peter 278
1495 27 Aug 12 peter 279       MY_VERSION_early([A], [B], [C+1], [true])
1495 27 Aug 12 peter 280
1495 27 Aug 12 peter 281    b) Add an entry in 'NEWS'
1495 27 Aug 12 peter 282
1495 27 Aug 12 peter 283 8<---
1495 27 Aug 12 peter 284 version A.B.[C+1] (released NOT YET)
1495 27 Aug 12 peter 285 8<---
1523 28 Sep 12 peter 286       The date is set when version A.B.[C+1] is released.
1495 27 Aug 12 peter 287
1495 27 Aug 12 peter 288    c) Commit changes to the repository,
1495 27 Aug 12 peter 289
1495 27 Aug 12 peter 290    #> svn ci -m "Bumping version"
1495 27 Aug 12 peter 291
1495 27 Aug 12 peter 292 14. Send an announcement to svndigest-users@lists.sourceforge.net
1582 09 Mar 15 peter 293     using 'announcement.txt' as template.
1495 27 Aug 12 peter 294
1495 27 Aug 12 peter 295 15. Create a macport ticket, https://trac.macports.org/newticket, with
1495 27 Aug 12 peter 296       summary='svndigest A.B.C',
1495 27 Aug 12 peter 297       type=update,
1495 27 Aug 12 peter 298       keywords="haspatch maintainer",
1495 27 Aug 12 peter 299       and port=svndigest.
1495 27 Aug 12 peter 300     Attach 'Portfile.diff' to newly created ticket.
1495 27 Aug 12 peter 301
1495 27 Aug 12 peter 302
1495 27 Aug 12 peter 303 --------------
978 12 Dec 09 peter 304 Copyright (C) 2005, 2006 Jari Häkkinen
978 12 Dec 09 peter 305 Copyright (C) 2007, 2008 Jari Häkkinen, Peter Johansson
1637 30 Mar 23 peter 306 Copyright (C) 2009, 2012, 2015, 2023 Peter Johansson
84 13 Mar 06 jari 307
687 04 Aug 08 peter 308 This file is part of svndigest, http://dev.thep.lu.se/svndigest
84 13 Mar 06 jari 309
149 12 Aug 06 jari 310 svndigest is free software; you can redistribute it and/or modify it
84 13 Mar 06 jari 311 under the terms of the GNU General Public License as published by the
693 11 Sep 08 jari 312 Free Software Foundation; either version 3 of the License, or (at your
84 13 Mar 06 jari 313 option) any later version.
84 13 Mar 06 jari 314
149 12 Aug 06 jari 315 svndigest is distributed in the hope that it will be useful, but
149 12 Aug 06 jari 316 WITHOUT ANY WARRANTY; without even the implied warranty of
149 12 Aug 06 jari 317 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
149 12 Aug 06 jari 318 General Public License for more details.
84 13 Mar 06 jari 319
84 13 Mar 06 jari 320 You should have received a copy of the GNU General Public License
693 11 Sep 08 jari 321 along with svndigest. If not, see <http://www.gnu.org/licenses/>.

Generated on Wed Aug 30 02:20:48 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)