For other information, see the Ghostscript overview and the instructions on how to build Ghostscript.
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.
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.
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 /usr/local/bin under the name (say) cvs3:
#!/bin/sh
exec env CVS_RSH=ssh cvs -z3 -d{username}@ghostscript.sourceforge.net:/home/groups/ghostscript/cvs "$@"
where {username} is your SourceForge user name. The relevant directories in this tree are called
bug-data/{bug#}/{file}
bp-dist.pdf bp-gs.pdf bp.ps report
Assuming you keep a local checked-out copy of the private CVS tree under a directory named sf, the procedure for creating the structure for bug # 109999 with an uploaded data file might look like this:
cd sf/bug-data mkdir 109999 cvs3 add 109999 If a report file is required: Create report file as 109999/report cvs3 add 109999/report If test files are required: Copy test file to 109999/xyz cvs3 add 109999/xyz etc. cvs3 commit
Sourceforge CVS 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.
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.
A concise and useful document for working with CVS branches is Jeff Semke's CVS Branch and Tag Primer. A somewhat more detailed explanation is the Branching and merging section from the CVS documentation by Pascal Molli.
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.
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.
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.
Always supply a descriptive log message for your commits. These log messages are used to automatically generate the News.htm 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.
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.
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].)
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 News.htm 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.
All patches must be reviewed before being committed. Please email your patch to gs-code-review@ghostscript.com. 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.
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 <raph@artofcode.com> and include your snailmail address for a hardcopy assignment form.
When adding or removing files, don't forget to invoke cvs add or cvs rm.
When adding files, update the file roadmap in doc/Develop.htm.
When adding or removing files other than .c or .h: If the files will be used at runtime, check the install list in unixinst.mak.
When adding .c files, update the relevant .mak file (usually devs.mak, int.mak, or lib.mak).
When adding new documentation, add a link to doc/Readme.htm and a short blurb describing the contents of the file.
When adding or changing fonts, update lib/Fontmap.GS, fonts.mak, and possibly the compiled fonts in gs.mak and the examples in doc/Fonts.htm.
When adding .ps files, update doc/Psfiles.htm.
Likewise, you will want to delete any references for a file you remove from Ghostscript.
Copyright © 2000 artofcode LLC. All rights reserved.
This file is part of AFPL Ghostscript. See the Aladdin Free Public License (the "License") for full details of the terms of using, copying, modifying, and redistributing AFPL Ghostscript.
Ghostscript version 7.03, 20 October 2001