			Notes for Developers                         -*-text-*-
			--------------------

You will need to install several GNU tools to be able to use the
cvs sources.  If you do not have these tools available, build from
the tar file distribution instead, available from ftp.fvwm.org.

To build from the CVS sources, you will need:
  * GNU gcc
  * GNU make
  * autoconf (version >= 2.13)
  * automake (version >= 1.4)


After the *initial* checkout of the sources, (see cvs.html) you
will need to execute the following commands from the top of the
source tree.

    aclocal
    automake --add-missing
    autoreconf

If the config.h.in file has been changed at the time automake is
called, (e.g. when building from a fresh CVS tree), both commands
have to be called twice to get the distribution built properly
(this seems to be a bug in autoconf):

    aclocal
    automake --add-missing
    autoreconf
    automake --add-missing
    autoreconf

There will be some warnings, which are ignorable as long as you
get a working configure script: the configure script will fix all
those problems.

Now, configure and build as per INSTALL.fvwm and INSTALL.  If
configure fails, please look through `config.log' for clues.


Development Rules of the Road
-----------------------------

 1) _Every_ change must be properly ChangeLogged.  If you use
    Emacs, you can do this oh-so-trivially with the "C-x 4 a"
    command; it will add a header (if it's a new day), the name of
    the file, and even the name of the function you're currently
    in.

    If you start adding them as you change functions, it'll soon
    become second-nature and we'll get proper ChangeLogs.

    If you don't use Emacs, please mimic the format of all the
    other log entries when adding your own.

 2) If you make a user-visible change please add a blurb about it
    to the NEWS file.  A couple sentences is fine; don't repeat
    the documentation but give folks enough of an idea so they can
    decide if they want to learn more.  Bug fixes (unless they're
    _really_ user visible) shouldn't be noted in the NEWS file.

 3) If you add a new user-visible feature, don't forget to update
    the appropriate man pages at the same time!

 4) Bug fixes may be committed at any time (unless we're in code
    freeze for a release), usually without much review (unless you
    want someone else to look at it).  All our code freezes,
    etc. are merely procedural, not enforced, so it's important
    you read fvwm-workers and keep up-to-date with the current
    state of the tree.

 5) New features should be discussed on the list to ensure
    everyone thinks they're "appropriate" (one of the goals of
    fvwm is to be relatively efficient, remember, which means we
    don't necessarily want the kitchen sink).

 6) If the new feature is large enough, unstable enough, or not
    targeted at the next release, it should go on a private
    branch.  Otherwise, consensus will probably have it installed
    on the main branch.

 7) Before adding a new feature think twice if it could perhaps be
    implemented as a module (perhaps after some extension of the
    fvwm<->module communication protocol). Moving features in
    modules helps to keep fvwm itself clean and efficient.


        ** Of course, compile and test before committing! **


Dealing with CVS
----------------

All details about dealing with CVS should be found in cvs.html.
Go look there!


Doing the JitterBug
-------------------

If you haven't already noticed them, now is the time to visit our
bug tracking pages:

  http://www.fvwm.org/cgi-bin/fvwm-bug

Anybody can submit or view bug reports there.

Developers with CVS write access can also update the bug database
(whee!).  To do so, you have to go to the Jitterbug page, but then
tack a ".private" on to the end of the URL:

  http://www.fvwm.org/cgi-bin/fvwm-bug.private

Then you'll be asked to authenticate.  The username and password
are the same as you use for the CVS repository.

You'll probably want to bookmark that page.


Changing a Makefile
-------------------

First of all, NEVER edit anything named Makefile or Makefile.in.
These are both derived from the corresponding Makefile.am.  The
most common reason for editing is to change the list of sources.

Steps: 1. edit foo/blah/Makefile.am
       2. re-run "make" from the top of the build directory

Step 2 will take care of rebuilding the Makefile.in and Makefile
from your changed Makefile.am.

Makefile.am has a simple format, basically:

        bin_PROGRAMS = fvwm

        fvmw_SOURCES = blah.c blah.h foo.c foo.h ...

Notice that you have to add all files, C-code *and* headers, to
the _SOURCES line.  This is vital, because this is the list of
files that are packed into the distribution.  If you leave one
out, nobody will be able to build the distributed tar file!


Changing configure.in
---------------------

The most common reason to do this is to change the version string.
If you're editing it for any other reason, I will assume you know
what you're doing.

Steps: 1. edit configure.in, and find the line containing
          AM_INIT_AUTOMAKE(fvwm, x.y.z) at the top of the file
       2. change x.y.z to the new version string
       3. re-run "make" from the top of the build directory

Step 3 will take care of rebuilding the configure script, and
usually all the other Makefiles.


Building an official distribution
---------------------------------

By this, I mean the files fvwm-x.y.z.tar.gz and
fvwm-x.y.z.tar.bz2.  It is important to do all steps in the given
order!

Preparations:

  - Make sure you have all optional libraries installed.
  - When building a release, update the CVS sources first. For a
    stable release it is best to throw away the whole source tree
    and check it out from scratch to ensure all source files have
    been added to CVS.
  - For a stable release, change the dates in docs/fvwm.lsm.in,
    fvwm/fvwm.1 and fill in the release date in NEWS.  Commit
    these changes.
  - For a stable release, update docs/ANNOUNCE file.  For the
    first version of a major release (e.g. 2.6.0) all user visible
    changes have to be mentioned.  For the following maintenance
    releases *all* code changes have to be listed.  This is
    usually done by copying all entries from the NEWS file.  Don't
    forget to proof read the file as it will be sent to the
    fvwm-announce mailing list.

Configuration tests:

  Note that you need to have actually build everything before
  packing the distribution, hence steps 3 to 5.  Among other
  things, this generates the proper dependency information for
  insertion into Makefile.in's generated by "make distcheck2".

  - Run
      automake --add-missing; autoreconf
    If you checked out fresh sources in, run the same line again
    (automake generates a file that autoreconf needs and
    autoreconf generates a file that automake needs.  If you fail
    to do so, the tarball may not contain all the necessary files.)
      automake --add-missing; autoreconf
  - If you are building a stable release, remove the config.cache
    file if there is one.  Of course doing this for a development
    release won't hurt either.
  - Run
      ./configure
  - Make sure configure detects all optional libraries except the
    ones that are recommended not to be used.  Repeat the previous
    step until configure finds everything.  Building a release
    without all optional libraries should be a rare exception.

Compile tests:

  - Run
      make clean
  - Double check that you get no warnings during the build (the
    options for compilers other than gcc may be different):
      make CFLAGS="-g -O2 -Wall -Werror"
    On some systems, the system include files generate warnings.
    On such a system you have to omit the -Werror option and check
    the output of the compilation run for warnings manually.  It
    is important to use the -O2 option because some versions of
    gcc seem to have a bug: when -Wall is used, but not -O2, no
    warnings are generated at all.  The only warning that can be
    safely ignored is this: "the use of `tempnam' is dangerous,
    better use `mkstemp'"
  - Fix all warnings and problems, commit the changes and repeat
    the previous step until no more warnings occur.

Build and test the release tarballs:

  The next step will create the tar file, then unpack it and
  attempt to build fvwm from it and install to a scratch
  directory.  This makes sure that you really *did* include all
  the files necessary to build the package into the tar file.  It
  may be hard to appreciate how useful this is, until it has
  reminded you that you forgot file "foo.h" in some _SOURCES line.
  But trust me, it will save your bacon in this way some day!

  - Run
      make distcheck2
  - Ensure that you see the messages
      "fvwm-x.y.z.tar.gz is ready for distribution"
    and
      "fvwm-x.y.z.tar.bz2 - ready for distribution"

Update the release dates and numbers:

* Important note: Before you proceed, please ask yourself if the
  code is ready to be released:

  - Have you committed patches only hours or even minutes ago?
  - Have there been any big changes in the last few days?
  - Are there any important parts that are not well tested?
  - Are you tired from work or have you been hacking fvwm for many
    hours in a row?

  Should your answer to any of these questions be 'yes', please do
  take a break now and reconsider, especially if this going to be
  a stable release.

  The steps above are not critical and can not screw up anything
  bad.  This is not true for what follows.  If you do something
  wrong now, you will have a hard time cleaning up the mess.
  Should something go wrong and you are not sure about the correct
  fixes, please ask on the fvwm-workers list for help.

  Be sure to do the next two steps in that order, so you get the
  label on the right version of configure.in.

  - Tag the CVS tree:
      cvs tag version-x_y_z
  - Increase the version number in configure.in (see above) and
    commit this change.
  - Create an entry in the ChangeLog file indicating the release.
    Commit this change.
  - Create a new section for future changes in the NEWS file.
    Commit this change.

Update the development branch:

  - For a stable release, copy the NEWS from the stable branch to
    the development branch and update the link in the same
    document.

Update fvwm-web:

  - Update the release numbers in fvwm-web/index.html and
    fvwm-web/download.html.  Generate ChangeLog entries for the
    changes and commit them to cvs.
  - Use fvwm-web generated/txt2html.sh to update the NEWS, FAQ and
    AUTHORS file.  This assumes the fvwm-web module is located in
    a directory fvwm-web and the development sources are in a
    sibling directory fvwm.
      cd fvwm-web/generated && \
        ./txt2html.sh ../../fvwm/NEWS && \
        ./txt2html.sh ../../fvwm/AUTHORS && \
        ./txt2html.sh ../../fvwm/docs/FAQ
    Commit these changes.

Upload the release:

  - Upload the files fvwm-x.y.z.tar.gz and fvwm-x.y.z.tar.bz2 to
    ftp://ftp.fvwm.org/pub/incoming/fvwm
  - Notify fvwm-owner@fvwm.org of the upload.

Announce the release:

  - Once the tarballs are in place, mail the ANNOUNCE file to the
    usual places, at least to fvwm-announce.
