source: trunk/README.developer

Last change on this file was 1582, checked in by peter, 2 years ago

fix typo

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