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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>AFPL Ghostscript maintenance procedures</title>
<!-- $Id$ -->
<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
</head>
<body>
<!-- [1.0 begin visible header] ============================================ -->
<!-- [1.1 begin headline] ================================================== -->
<h1>AFPL Ghostscript maintenance procedures</h1>
<!-- [1.1 end headline] ==================================================== -->
<!-- [1.2 begin table of contents] ========================================= -->
<h2>Table of contents</h2>
<blockquote><ul>
<li><a href="#Introduction">Introduction</a>
<li><a href="#Problem_reporting">Problem reporting</a>
<ul>
<li><a href="#Uploading_test_data">Uploading test data</a>
</ul>
<li><a href="#CVS">Rules for CVS commits</a>
<li><a href="#Adding_or_removing_files">Adding or Removing Files</a>
</ul></blockquote>
<!-- [1.2 end table of contents] =========================================== -->
<!-- [1.3 begin hint] ====================================================== -->
<p>For other information, see the <a href="Readme.htm">Ghostscript
overview</a> and the instructions on how to <a href="Make.htm">build
Ghostscript</a>.
<!-- [1.3 end hint] ======================================================== -->
<hr>
<!-- [1.0 end visible header] ============================================== -->
<!-- [2.0 begin contents] ================================================== -->
<h2><a name="Introduction"></a>Introduction</h2>
<p>
This document describes various maintenance procedures associated with AFPL
Ghostscript. It is only meant for developers actively working on AFPL
Ghostscript; some parts of it are only relevant to developers who are
members of the ghostscript group on SourceForge.
<hr>
<h2><a name="Problem_reporting"></a>Problem reporting</h2>
<h3><a name="#Uploading_test_data"></a>Uploading test data</h3>
<p>
SourceForge currently provides no supported method for associating test data
files with a problem report. Submitters can always include a URL in their
public report, but sometimes the test files need to remain private.
<p>
To allow uploading of private test files, we have set up a CVS tree on a
SourceForge server, accessible only to members of the ghostscript group.
The simplest way to access this tree is to place the following script in
<b><tt>/usr/local/bin</tt></b> under the name (say) <b><tt>cvs3</tt></b>:
<blockquote><pre>
#!/bin/sh
exec env CVS_RSH=ssh cvs -z3 -d<em>{username}</em>@ghostscript.sourceforge.net:/home/groups/ghostscript/cvs "$@"
</pre></blockquote>
<p>
where <em>{username}</em> is your SourceForge user name. The relevant
directories in this tree are called
<blockquote><pre>
bug-data/<em>{bug#}</em>/<em>{file}</em>
</pre></blockquote>
The file named <tt>report</tt> should contain any bug report information
(such as the name or company of the original submitter) that shouldn't be
included in the public bug posting, if needed. For example, the contents of
<tt>bug-data/102146/</tt> are
<blockquote><pre>
bp-dist.pdf bp-gs.pdf bp.ps report
</pre></blockquote>
<p>
Assuming you keep a local checked-out copy of the private CVS tree under a
directory named <b><tt>sf</tt></b>, the procedure for creating the structure
for bug # 109999 with an uploaded data file might look like this:
<blockquote><pre>
cd sf/bug-data
mkdir 109999
cvs3 add 109999
<em>If a report file is required:</em>
<em>Create report file as </em><tt>109999/report</tt>
cvs3 add 109999/report
<em>If test files are required:</em>
<em>Copy test file to </em><tt>109999/xyz</tt>
cvs3 add 109999/xyz
<em>etc.</em>
cvs3 commit
</pre></blockquote>
<hr>
<h2><a name="CVS"></a>Rules for CVS Commits</h2>
<p>
<a href="http://sourceforge.net/cvs/?group_id=1897"
class="offsite">Sourceforge
CVS</a> is the primary repository for Ghostscript code changes. This
section describes a few rules intended to make life easier
for people working with this code base.
<p>
At any given time, there are usually two active branches: a stable
branch and a development branch. The development branch is HEAD, which
is the default when doing a checkout without a -r flag. At the time of
this writing (6 October 2000), the stable branch is tagged
GS_6_5.
<p>
A concise and useful document for working with CVS branches is Jeff
Semke's <a href="http://www.psc.edu/~semke/cvs_branches.html"
class="offsite">CVS
Branch and Tag Primer</a>. A
somewhat more detailed explanation is the <a
href="http://www.loria.fr/~molli/cvs/doc/cvs_5.html"
class="offsite">Branching and
merging</a> section from the CVS documentation by Pascal Molli.
<p>
For new development commits, you can basically ignore the
branches. Just commit to the HEAD branch. For bug fixes for the stable
branch, it is your responsibility to commit to both the stable branch
and, if appropriate, HEAD. Commits to HEAD are appropriate if they are
in an area not being actively reworked, if the development version
exhibits the same bug symptoms, and if the patch fixes these
symptoms.
<p>
When modifying a number of files for a single issue, please group them
together as a single commit. For two separate sets of changes dealing
with two different issues, there should be two commits.
<p>
You should strive not to introduce any new bugs with your
commit. Always make sure the code compiles before committing. Test the
changes with several files, including the problem file in the case of
a bug fix, and other files that may have been affected by the
changes.
<p>
Always supply a descriptive log message for your commits. These log
messages are used to automatically generate the <a
href="News.htm">News.htm</a> file and History changelogs, and are also
crucial for navigating CVS using the CVSweb gateway. Please try to
keep the style of the descriptions similar to those in the current
History#.htm files.
<p>
Log messages beginning with 'Fix' are treated specially. Such messages are
put under the "Fixes problems" heading when the History files are
generated. Additionally, if the first four characters are 'Fix:' this is removed
(i.e., "Fix: The xyz" becomes "The xyz", but "Fixes xyz" is copied unchanged).
This feature is intended for explicit bugfixes and should be avoided for
enhancements or commits with long explanations.
<p>
Information about who changed what, when, and why is maintained in the
CVS logs. In general, a file should be a clean representation of the
current version rather than a history trail of how it got
there. Keeping old code around for reference is usually not necessary,
as it is stored in the CVS diffs. When necessary, use #if / #endif, or
descriptive conditionals such as #ifdef OLD_CMAP_TABLES. Do not
comment out old code. (A very few files that are distributed separate
from Ghostscript have a change log at the beginning, which should be
maintained: currently, only ansiknr.c and md5.[ch].)
<p>
Additionally, if your patch removes a feature, changes an interface or
otherwise creates an incompatibility with the last release, you
must add an entry to the "Incompatible changes" section of <tt>News.htm</tt>
as this information can only be generated manually.
This admonition applies to api changes that might
affect other developers as well as user issues like switch behavior.
Upon release, the accumulated incompatible changes will be moved to the
relevant History file, and the News collection in cvs will be wiped clean
for the next version.
<p>
All patches must be reviewed before being committed. Please email your
patch to <a
href="mailto:gs-code-review@ghostscript.com">gs-code-review@ghostscript.com</a>.
Make sure to include your commit comment and any other information
that would be helpful for the review. Also, please identify which
branches the patch is intended for.
<p>
If you are not an employee or consultant of Artifex or artofcode, then
we need a copyright assignment form so we can incorporate your
changes. Please email Raph Levien <<a
href="mailto:raph@artofcode.com">raph@artofcode.com</a>> and
include your snailmail address for a hardcopy assignment form.
<h2><a name="Adding_or_removing_files"></a>Adding or removing files</h2>
<p>
When adding or removing files, don't forget to invoke <b><tt>cvs
add</tt></b> or <b><tt>cvs rm</tt></b>.
<p>
When adding files, update the file roadmap in
<b><tt>doc/Develop.htm</tt></b>.
<p>
When adding or removing files other than .c or .h: If the files will be
used at runtime, check the install list in <b><tt>unixinst.mak</tt></b>.
<p>
When adding .c files, update the relevant <b><tt>.mak</tt></b> file
(usually <b><tt>devs.mak</tt></b>, <b><tt>int.mak</tt></b>, or
<b><tt>lib.mak</tt></b>).
<p>
When adding new documentation, add a link to <tt>doc/Readme.htm</tt> and
a short blurb describing the contents of the file.
<p>
When adding or changing fonts, update <b><tt>lib/Fontmap.GS</tt></b>,
<b><tt>fonts.mak</tt></b>, and possibly the compiled fonts in
<b><tt>gs.mak</tt></b> and the examples in
<b><tt>doc/Fonts.htm</tt></b>.
<p>
When adding .ps files, update <b><tt>doc/Psfiles.htm</tt></b>.
<p>
Likewise, you will want to delete any references for a file you
remove from Ghostscript.
<!-- [2.0 end contents] ==================================================== -->
<!-- [3.0 begin visible trailer] =========================================== -->
<hr>
<p>
<small>Copyright © 2000 artofcode LLC.
All rights reserved.</small>
<p>
<small>This file is part of AFPL Ghostscript. See the <a
href="Public.htm">Aladdin Free Public License</a> (the "License") for full
details of the terms of using, copying, modifying, and redistributing
AFPL Ghostscript.</small>
<p>
<small>Ghostscript version 7.03, 20 October 2001
<!-- [3.0 end visible trailer] ============================================= -->
</body>
</html>
|
