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

      --  If the change affects the plotting routines: Verify that
          tests/testbench_draw_manual.wxm still holds the right
	  results.

      --  If the change affects drawdf() or plotdf(): Verify that
          tests/testbench_drawdf_manual.wxm still holds the right
	  results.
	  
      --  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

      --  If the change affects the plotting routines: Verify that
          tests/testbench_draw_manual.wxm still holds the right
	  results.
	  
      --  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/include-maxima.texi.in
          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 repository "website", particularly "README.md" 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. Don't forget to add it to 
    the top level "Makefile.am" so that it will be included in the
    release tarball.

  9.4  Verifying the functionality of the maxima tarball

    The autotools offer a few make targets that allow to verify the
    maxima release:

    $ make pdf
    isn't done automatically on "make all" so it is good to test if this
    make target works.
    
    $ make check
    runs the standard testsuite, the testsuite for the share packages
    and the tests for the ask_* functions for all lisps maxima is compiled
    with and returns an error if any test unexpectedly failed.

    $ make distcheck
    compiles maxima, builds a release tarball, extracts this tarball,
    compiles it and runs "make check" on it in order to find out if
    "make dist" has produced a working tarball no files are missing from.

    $ mkdir build
    $ ../configure
    $ make
    $ make distcleancheck
    tests if "make disclean" brings maxima back into the original state.
    this is very handy when building debian packages.
    
    make installcheck
    $ tests if "make install" results in a working maxima release.

    Note that with Ubuntu Cosmic/Disco in Jan 2019 still only the first
    two of these make targets run without errors.

  9.5  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.6  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 traditionally created by RPM.

    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

    Debian packages can be built the following way:

    - Install clisp, sbcl, gcl, ecl and debhelper.
    - checkout the branch DebianPackaging
    - Update the changelog contained in its debian directory: From there the
      e-mail address of the packager and the version number of the Debian
      package are taken. It also is important that gpg knows the private key
      for the e-mail address mentioned in the last ChangeLog entry.
    - copy the debian directory into the directory containing the contents of
      the release tarball.
    - cd into this directory and type:
      $ debuild
    - debuild will now complain that the source is missing and tell under which
      names it will accept the tarball. Rename the tarball to this name and start
      debuild again.
    - a few minutes later gpg will ask for the key's password in order to sign
      the newly built packages.

    Unfortunately just using the Debian package included in the autotools won't
    equip the Maxima package it generates with the metadata that allows to
    install the wxMaxima package shipped with Debian and Ubuntu.
    
  9.7  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.8  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://wxmaxima-developers.github.com/wxmaxima/
    or sending the project maintainer an email should be sufficient
    for this task.