123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273 |
- <!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: Maintain.htm,v 1.23.2.2 2002/02/01 05:31:25 raph Exp $ -->
- <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.04, 31 January 2002
- <!-- [3.0 end visible trailer] ============================================= -->
- </body>
- </html>
|