README.developers-howto

  Maxima project Git / build system HOWTO


  1  General

      Makefile.am is the file to modify, NOT Makefile
      (Makefile is generated automatically from Makefile.am)

      "make install" catches Makefile problems
      that are not detected by "make" alone

      Adding / removing files often leads to Makefile problems

      To update your repository, execute
      git pull  # assuming origin/master points to the SF Maxima repo

      Workflow with Git:
      git pull                      # update your repo
      git checkout master           # work off master
      git checkout -b scratch-pad   # create a working branch
      <do development, tests, commits, then, once satisfied...>
      git checkout master           # put yourself on master branch
      git pull                      # update your repo, again
      git merge scratch-pad         # merge development work into master
      git push origin master        # push to SF Maxima repo

      BE SURE NOT TO PUSH YOUR SCRATCH-PAD!

  2  Renaming something in Git

      --  Create a scratch/development branch as in 1.
  
      --  git mv X Y
          This moves X to Y and preserves the history.
	  Like any other change, this needs to be committed
	  as a separate step.

  3  Adding / removing a file in maxima/src

      --  Create a scratch/development branch as in 1.
  
      --  Add new file X, then execute
          git add X; git commit -m 'Message' -- X

      --  Remove old file X
          git rm X
          Then execute "git commit" as above

      --  Add / remove file name from maxima/src/Makefile.am

      --  Add / remove file name from maxima/src/*-depends.mk

          NOTE: There are several *-depends.mk files. These are
          theoretically updated automatically but to the best
          of my knowledge it is necessary to fix them by hand.

      --  Add / remove file name in maxima/src/maxima.system

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Merge your work onto master and push the changes as in 1.


  4  Adding / removing a file in maxima/share

      --  Copy new file / remove old file
          as you did in 3.

      --  Add / remove file name in maxima/share/Makefile.am

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Merge your work onto master and push the changes as in 1.


  5.1  Creating a new share package

       E.g., new package name = my_package

      -- Naming conventions:

         write_long_names_like_this, andNotLikeThisPlease,
         norlikethiseitherthanks

         spell_out_names, dnt_try_sv_typng_w_abbrvs_tnx

      -- Create a new directory my_package

      -- Put Lisp and/or Maxima files in the directory

         At least one file must be named my_package.lisp or my_package.mac
         Otherwise load(my_package) fails

      -- Create texinfo documentation file my_package.texi
         (PLEASE CREATE DOCUMENTATION, THANK YOU)

         my_package.texi goes in maxima/doc/info
         (same as other texinfo files)

         Use maxima/share/template.texi as a template for my_package.texi

      -- Create test file rtest_my_package.mac
         (PLEASE CREATE A TEST FILE, THANK YOU)

         Test file contains pairs of expressions:
         input expression, then expected result

         batch("my_package/rtest_my_package.mac", test);
         executes the test


  5.2  Adding a directory in maxima/share
  
      --  Create a scratch/development branch as in 1.

      --  Make the new directory and put the new files in it

      --  Add the all the files in your new directory and commit this change:
          git add .
	  git commit -m 'Message' -a

      --  Put the my_package files on the file list of maxima/share/Makefile.am

      --  Add my_package to SHARE-SUBDIRS-LIST in maxima/src/init-cl.lisp

      --  Move my_package.texi to maxima/doc/info

          Put my_package.texi on the list of files in
          maxima/doc/info/Makefile.am

          Put my_package on the list of topics in maxima/doc/info/maxima.texi
          See instructions in comments at top of maxima/share/template.texi

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Commit and push your work as in 1.


  6  Adding / removing a file in maxima/tests

      --  Create a scratch/development branch as in 1.

      --  Copy new file / remove old file
          and execute "git add" / "git rm"

      --  Add / remove file name in maxima/tests/Makefile.am

      --  Add / remove file name in maxima/tests/testsuite.lisp

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Commit and push your work as in 1.


  7  Updating the website

    See the Git module "site-xml", particularly "README" there.


  8.1  Backups of Git

    All you need is the rsync tool and some disk space.

    Issue the following command:

    rsync -av 'rsync://maxima.git.sourceforge.net/gitroot/maxima/*' .


  8.2  Backups of the ML subscribers list

    You need to be a list admin to do that. Other then that you only
    need a mail client to send mailman commands to
    maxima-request@math.utexas.edu

    The command to get the subscribers list is "who" followed by the
    list admin password. Sending an empty mail with "who XXX" in the
    subject line should be enough.

    I have the following cron.weekly script to do this automatically:

    | #! /bin/sh
    | 
    | su myuser -c "echo end | mail -s \"who password\" maxima-request@math.utexas.edu"


  8.3  Other Backups

    Backups of the following stuff would be nice too:

    - wiki

    - bug database


  9  Releases

  9.1  Release policies

    Releases are prepared (nominally) three times a year, on April 1,
    August 1, and December 1. Releases simply package whatever seems
    stable at that time.

    It is the responsibility of developers (not the release
    administrator) to copy bug fixes from the release branch to master
    or vice versa (it doesn't matter whether bug fixes are introduced
    on one branch or the other).

    I don't recommend major changes on a release branch, but there is
    really nothing to stop it. As always I'll appeal to good judgement.

    If I've forgotten some step, please add it to this document.

  9.2  Release numbering

    The first release on the 5.mm release branch is 5.mm.0, the second
    is 5.mm.1, third 5.mm.2, etc. The highest number on the branch is
    the "best" or, at least, the most committed-to version. There is no
    release candidate numbering.

    The version major number has been 5 for many years. If you feel like
    changing it to, say, 6, well, there's nothing to stop you.

  9.3  Changelog

    The changelog for 5.mm is named ChangeLog-5.mm.md (the suffix .md
    indicating that it is in so-called "markdown" format). To obtain the
    raw material for the changelog:

    $ git log branch-5.${mm-1}-base..HEAD

    Use the git-log output as the basis for ChangeLog-5.mm.md. Use your
    best judgement as to what to include; the git-log output is
    typically much, much larger than the changelog. Look at previous
    changelogs to see the markdown format and organization.

    Commit ChangeLog-5.mm.md to master.

  9.4  Git commands for releases

    Release versions live on a branch named branch-5_mm, and are tagged
    5.mm.0, 5.mm.1, 5.mm.2, etc. The Git tag must be the same as the
    version number declared to autoconf.

    $ git checkout master
    $ git tag -a branch-5_mm-base
    $ git push --tags origin master
    $ git checkout -b branch-5_mm
    $ <edit configure.ac to set version number to 5.mm.0>
    $ git add configure.ac && git commit
    $ git tag -a 5.mm.0

    <at this point, verify that you can build packages BEFORE you push>

    $ git push --tags origin branch-5_mm-base
    $ git checkout master
    $ <edit configure.ac to set version number to 5.${mm-1}post>
    $ git add configure.ac && git commit
    $ git push origin master

    Repeat 5.mm.0 stuff (edit configure.ac and tag) for 5.mm.1, 2, 3, ....

    To copy bug fixes from one branch to another:

    $ git cherry-pick -x <commit hash>

  9.5  Building a release

    $ git checkout branch-5_mm
    $ sh bootstrap
    $ ./configure
    $ make dist-gzip

    At this point you now have maxima-5.mm.nn.tar.gz.
    
    Binaries for Linux are created by RPM. It can be argued that Debian
    packages would be more widely useful. Feel free to create Debian
    packages instead of RPMs. If, in addition, you can create MacOS 
    binaries, so much the better.

    I'll assume you know how to build stuff with RPM. Copy the tar.gz
    to <path to rpm build tree>/SOURCES/. Then:

    $ rpmbuild -ba maxima.spec

  9.6  Uploading files

    $ sftp mysfusername,maxima@frs.sourceforge.net
    > cd /home/frs/project/m/ma/maxima
    > cd Maxima-Linux
    > mkdir 5.mm.nn-Linux
    > cd 5.mm.nn-Linux
    > lcd /path/to/rpms
    > put maxima-*5.mm.nn*.rpm
    > cd ..
    > mkdir 5.mm.nn-source
    > cd 5.mm.nn-source
    > lcd /path/to/tar.gz
    > put maxima-5.mm.nn.tar.gz
    > quit

  9.7  Announcements

    Post an announcement about every 5.mm.nn release to the Maxima
    mailing list. When it seems stable enough (i.e. no immediate plans
    to create another release) feel free to announce it in other forums,
    e.g. sage-devel.

    Since wxMaxima does do a simultaneous release with maxima and
    windows installers containing wxMaxima and maxima are usually
    published within hours of the new maxima release the wxMaxima
    developers beg to be informed in advance about the planned release
    date. Filing a ticket at http://andrejv.github.com/wxmaxima/
    or sending the project maintainer an email should be sufficient
    for this task.