			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.

    automake --add-missing
    autoreconf

If the config.h.in file 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):

    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 freeze, etc. is 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 = fvwm2

        fvmw2_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 a distribution
-----------------------

By this, I mean the files "fvwm-x.y.z.tar.gz" and "fvwm-x.y.z.tar.bz2".

Steps: 1. 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.
       2. Make sure you have XPM, the strokes library and a X server with
          the shape extension.
       3. Run
            automake --add-missing; autoreconf
	  If you checked out fresh sources in step 1, run the same line
          again:
            automake --add-missing; autoreconf
       4. If building a stable release, remove the config.cache file.
       5. ./configure
       6. make clean
       7. 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"
       8. make distcheck2
       9. Ensure that you see the message
          "fvwm-x.y.z.tar.gz ready for distribution"

The steps 3 to 9 can be done by running the script utils/make_fvwmdist.sh
from the top level directory of the source tree.  You can also call
this script with the -r option.  In this case the it will also do
the steps 9 to 12.  The release number will be increase by one after
the second digit.  The script will ask you for a name and mail address
to be used in the ChangeLog entry.

Note that you need to have actually built 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 in step 8.

Step 8 will create the tar file, then unpack it and attempt a build &
install (to a scratch directory, not /usr/local).  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!


If this is to be an "official", labeled release, then do also the
following:

      10. Tag the CVS tree:
          cvs tag version-x_y_z
      11. Increase the version number in configure.in (see above)
          and `cvs commit' this change.
      12. Create entries in the ChangeLog and NEWS files indicating the
          release.
      13. Upload the files fvwm-x.y.z.tar.gz and fvwm-x.y.z.tar.bz2 to
	  ftp://ftp.fvwm.org/pub/incoming/fvwm
      14. Notify fvwm-owner@fvwm.org of the upload.
      15. Update the release numbers in fvwm-wb/index.html and
          fvwm-web/download.html.
      16. Use fvwm-web generated/txt2html.sh to update the NEWS file
            cd fvwm-web/generated && ./txt2html.sh ../../fvwm/NEWS
      17. Make sure the web pages in fvwm-web point to the new release.

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

For a stable release, do not forget to change the date in
docs/fvwm.lsm.in.
