Checklist.txt

Checklist for doing a release
=============================

    - Run regression tests in as many Emacsen as possible.  Make sure
      there are no failures.

    - Proofread manual.

    - Update ChangeLog.  "make rcs2log" outputs the new information to
      stdout - it can then be prefixed to the existing ChangeLog.

    - Add `Release 5.xx' tag to ChangeLog using C-x 4 a.  Release.py
      script looks for this.

    - Distill changes for NEWS file.

    - Proofread and update ANNOUNCEMENT, MANIFEST, NEWS, README for
      the new release.  Make sure the copyright statements in all
      files are up-to-date.

    - Update the web files in the admin directory:

      o  Create a new changes-5xx.php file from the new items i NEWS.
      o  Add a new entry for the changes file in changelinks.h.
      o  Update the version number in index.php, release.php and
	 anoncvs.php.
      o  Check at least release.php for correctness.

    - If there are any new files.el, make sure they've been inserted
      into Makefile.

    - Run "make release" to make all the tarballs and documentation.

      XX is the minor revision number of the new release.

      This creates the following files in dist:
	  cc-mode-5.XX.tar.gz
	  cc-mode.dvi.gz
	  cc-mode.ps.gz
	  cc-mode.rev.ps.gz
	  cc-mode.info.tar.gz
	  cc-mode.XEMACS.info.tar.gz
	  cc-mode.html.tar.gz

    - Update the SourceForge site:

      o  Do a new release in the SourceForge pages (see note below).
      o  Copy the manual files to the manual subdir.
      o  Unpack the standalone tarball into the web root dir and name
	 the subdir "src".
      o  Additionally, copy ChangeLog into the "src" subdir.
      o  Unpack cc-mode.html.tar.gz into the web root dir and name the
	 subdir "html-manual".
      o  Update the web files with cvs update.
      o  Check that the links work.

    - Send ANNOUNCEMENT file to
      cc-mode-announce@lists.sourceforge.net.  (Don't forget to use
      the correct sender and From header.)

    - Post ANNOUNCEMENT to the following newsgroups:
	gnu.emacs.sources
	comp.emacs
	comp.emacs.xemacs
	comp.lang.c
	comp.lang.c++
	comp.lang.objective-c
	comp.lang.java.softwaretools
	comp.lang.idl
	comp.lang.awk
      (Don't forget the correct sender here either.)

    - Tag the release using "./Release.py --tag XX" where XX is the
      number used above.  If you find a problem in the released
      tarball, retag using -T option.  Very important!  Make sure the
      tag is set before doing the bump (next step).

    - Bump the current release by running "./Release.py --bump XX+1"
      Do not do this until the previous release has been tagged, and
      only do this as a last step!

    - You're now ready to start hacking the next version.


Patch releases
==============

    -  Every "real" release beginning with 5.30 is a branch, tagged
       "Branch_5_30", "Branch_5_31", etc.

    -  There's also a normal tag on the form "Release_5_30" so that
       the original release version can be found.

    -  On the branch there are tags for so-called "patch releases",
       e.g. "Patch_5_30_1", "Patch_5_30_2", etc.

    -  A patch release is intended to be as lightweight as possible.
       Every time a fixed version should be spread to Emacs, XEmacs or
       the standalone dist, a patch release should be made for that
       version.  The reason is to make the version numbers in bug
       reports accurate.

    -  A patch release is made as follows:

       1.  Update the ChangeLog file with any changes that aren't
	   there already.  (You can e.g. use "make rcs2log", paste in
	   the output at the top of ChangeLog, and then edit it as
	   necessary.)
       2.  Add an entry "* Patch release 5.30.NN" to the top of the
	   ChangeLog.  NN is the patch count that's last in the
	   version string in cc-defs.el.
       3.  Commit it.  (Also make sure everything else that should go
	   in is committed.)
       4.  Do "cvs tag Patch_5_30_NN".
       5.  Use the file tree in this state to send it whereever it
	   should go.
       6.  Increase the patch count in the version string in
	   cc-defs.el and commit it.  That's the only place where the
	   patch count is present; it's enough to make it show in bug
	   reports and when people do M-x c-version.

       (Release.py automates some of this for a real release, but it's
       not yet adapted for patch releases.)

    -  Since patch releases are so lightweight, they can be made
       fairly easily and without discussion.  The only requirement is
       that the ChangeLog is updated (since it's necessary when
       merging the version into (X)Emacs).  Spreading and announcing a
       patch release is optional; one can e.g. make one only to give
       to the XEmacs people, or only to upload to the web site.
       Still, it's of course best to make it available in all three
       places.

    -  Note for SourceForge release: The patch release is mentioned in
       these web pages: index.php, release.php, changes-5XX.php.

    -  Every fix and improvement _must_ be committed to the
       development branch, i.e. the main trunk.  The only exception is
       if it only concerns code that isn't applicable there anymore.

    -  Bug fixes which are small or fairly safe should be committed to
       the patch branch so that they can be spread more quickly.
       Minor improvements are also ok if they don't affect the
       stability.  However, if an improvement would be large enough to
       warrant an entry in the NEWS file, it's probably too big to
       slip into the patch branch.

    -  To incorporate a fix into the other branch, one can do this
       right before it's committed:

	 > cvs diff -u | patch -d ../cc-other -p0

       "cc-other" is a tree where the other branch is checked out.  (A
       tip is to always have two trees checked out, one for each
       branch.)

       If the patch goes well, files in both trees can be committed
       conveniently with the same cvs command and the same message.

    -  When there's enough reason for it, the latest patch release is
       made available from the web site.  At that point it can be
       announced on cc-mode-help@gnu.org, or maybe even on all the
       places like a "real" release.

       "Enough reason" is typically either that some time has gone by
       so that a bunch of minor fixes have accumulated, or that a
       really nasty bug has been fixed.


SourceForge file release
========================

1.  Go to "Admin" -> "File Releases" -> "[Add Release]".
    (https://sourceforge.net/project/admin/newrelease.php?package_id=3849&group_id=3875
    might work).
2.  Upload the tarball to <ftp://upload.sf.net/incoming/>.
3.  Fill in the version number as the release name.
4.  Fill in "Release Notes" on the next page:
      Real release:
	See the CC Mode web site
	<http://cc-mode.sourceforge.net/changes-530.php> for details
	about this release.
      Patch release:
	This release contains only bugfixes since 5.30. See the
	ChangeLog for details.
    (It's not necessary to bother with more; change logs etc are
    elsewhere.)
3.  Add the the file.
4.  "Edit Files In This Release":
    Processor Type: Platform-Independent
    File Type: .gz <since .tar.gz doesn't exist among the choices>
5.  Blipp away an "Email Release Notice".


Installing CC Mode in (X)Emacs
==============================

This is how I (Martin) currently do it (cvs write access is required
for both):

1.  Do cvs update where CC Mode resides in the (X)Emacs tree.

    Emacs: lisp/progmodes/cc-*.el and man/cc-mode.texi.
    XEmacs: xemacs-packages/cc-mode in the package repository.

    Investigate the changes made by others in cc-*.el if there are
    any, and incorporate them in the CC Mode cvs if appropriate.

2.  Update the files by patching from the last installed version.
    This is to keep the changes made by others and that aren't wanted
    in the upstream CC Mode for some reason. (Such differences should
    be avoided as far as possible though, so they probably need to be
    discussed(*).)

    Upstream files that currently aren't included:

    Emacs: cc-guess.el, cc-lobotomy.el, cc-fix.el (not needed).

    XEmacs: None.  (cc-fix.el is, or at least was, needed to work
    around bugs in fairly recent XEmacs versions.  Besides, since the
    packages are released individually it's not certain which version
    of the XEmacs core it will be used with.)

3.  Do a quick test that the patched sources at least load correctly.

4.  Update the other files.

    For Emacs:

    o  Copy the applicable ChangeLog entries to lisp/ChangeLog.
       Combine them all to one entry at the current date.

       RMS prefers if the entries are condensed as much as possible to
       summarize the overall code changes between the versions.  I
       look through and remove entries that are superseded later on,
       but I don't spend overly much time on rewriting it all to be as
       compact as possible.

    o  If it's a real release, merge the new entries in NEWS into
       etc/NEWS.

    o  If man/cc-mode.texi was updated, write a note about it in
       man/ChangeLog.

    For XEmacs:

    o  Copy over MANIFEST, NEWS, README and cc-mode.texi if necessary.

    o  If it's a real release, simply write "Update to CC Mode X.XX"
       in xemacs-packages/ cc-mode/ChangeLog (that's apparently enough
       to satisfy the XEmacs people).

    o  If it's a patch release, add the applicable ChangeLog entries.
       It seems to be acceptable to keep the entries but change all
       dates to the current date.

    o  Update AUTHOR_VERSION in xemacs-packages/cc-mode/Makefile.  (Do
       not touch VERSION; the XEmacs release guy will do that when he
       has seen the message on xemacs-packages and makes a new package
       release.)

5.  Commit it.  Good commit messages with the relevant changes in each
    file are nice, but I don't necessarily take the time to do that.
    It's all there in the ChangeLog anyway (although the cvs logs
    arguably are a better place).

6.  For XEmacs: Send a message with the ChangeLog entries to
    xemacs-patches@xemacs.org.


*) One reason for differences:

RMS doesn't allow the use of functions from the cl package at runtime
since it isn't formally a part of Emacs.  Therefore some cl functions
have been more or less duplicated where they are used in the Emacs
cvs.

I (Martin) otoh refuse to comply with this "ban" against the cl
functions; Emacs provide no alternatives and it's insane to have to
duplicate this trivial functionality in every package that need it.  I
won't spend one minute maintaining such duplicate code just because
RMS doesn't like Common Lisp.  Afaik he has given no better grounds
for the "ban" of the cl package (at least not the simpler parts of it,
such as set manipulation and list search functions, which are what
this is about).

Note that I've discussed getting more cl functions "blessed" but found
it intractable (on the emacs-devel list, in August and September 2003,
the thread has the subject "cc-langs.el" or "Blessing cl functions").
Functions might get approved but it seems that they have to be
pondered individually.  That process is apparently very time consuming
for reasons that largely remain a mystery to me (it goes something
like "Emacs Lisp is not Common Lisp, so they can't simply be added").
So perhaps one or a couple can creep in in every release, which means
that it'll take somewhere between 50 and 200 years before Emacs will
have a decent set of approved basic utility functions.

Thankfully, the functions are afterall there already and there's no
practical problem using them.  Thus this silliness can be ignored,
which is exactly what I'm doing (except that I patch instead of
overwrite the files when I update them).