port science/paraview

[Matthew Seaman]

Anton Shterenlikht wrote:
> port science/paraview is far behind the current version.
> 
> I do understand that nobody really takes care of it,
> so please do not see this as a request. I'm grateful
> that somebody has created this port at all!
> 
> I'd like to help but I've never done any serious
> port work, just occasional patches.
> What is your estimate of the amount of work, and of
> skills required to bring this port up to date?
> 
> many thanks
> 

Hmmm... science/paraview is not too complicated as ports go.  It uses cmake
which is slightly unusual, and needs a bit of post-hoc modification to force
it to install stuff under /usr/local rather than /usr/X11R6 but that's not a
big deal.

If you're capable of configuring, compiling and installing this software
package outside of ports, and you have a fairly minimal amount of familiarity
with make(1) and Makefiles, then you stand a good chance of being able to
generate a set of patches to update the port, and could with a little practice
probably go on to become the maintainer.

Remember, the Porter's Handbook is your bible and reference for what all those 
USE_FOO and BAR_ARGS lines in the Makefiles actually mean.  Well, that and reading
the contents of the Makefiles in /usr/ports/Mk (these typically have extensive
comments describing what all the different variables are for) plus comparing
against prior art elsewhere in the ports tree.

To generate an update, I usually work through the following stages:

   0) Copy the port directory to a clean workspace somewhere

   1) Modify the PORTVERSION and PORTREVISION settings in the Makefile, plus
      make any tweaks to MASTER_SITES etc. that are required until you can 
      successfully run:

        # make makesum

      This will automatically download the distfiles and update the distinfo file.
      For the initial introduction of a new upstream version, any PORTREVISION line
      can be deleted, but be sure *not* to touch any PORTEPOCH lines.  

   2) Make sure all prerequisites ({BUILD,RUN,LIB}_DEPENDS) of the port are
      installed.  To avoid conflicts with other software, it's handy to work
      in a jail but you don't have to.  Installing into an alternative PREFIX
      and using an alternative PKG_DBDIR and PORT_DBDIR settings is almost as
      good. (ie. Prerequisites should go in the standard $LOCALBASE but the port
      in question can go into a custom $PREFIX.  Usually.)
 
   3) Attempt to build the port:

        # make

      If it doesn't work smoothly, try and diagnose what the problem is and fix
      it.  Repeat until you get a clean build.  This is very much the hardest
      part of updating a port, and can involve significant programming skills
      to write patches etc.

   4) Now is a good time to make any edits to pkg-message or other miscellaneous
      stuff.

   5) Make a record of what's installed under $PREFIX:

        # find /usr/local -print | sort > /tmp/local-files.before

   6) Attempt to install the port

        # make install

      Again, you may need to apply a few fixups here

   7) Record the contents of $PREFIX with the port installed:

        # find /usr/local -print | sort > /tmp/local-files.during

   8) Now attempt to remove the port:

        # make deinstall

       If the pkg-plist is wrong, you'll almost certainly see errors here.

   9) Record the contents of $PREFIX after removing the port:

         # find /usr/local | sort > /tmp/local-files.after

   10) Now, by comparing the differences between /tmp/local-files* it should
       be fairly obvious what, if any, modifications are needed in pkg-plist
       to account for any differences in the files installed by the newer 
       version of the port.

   11) Return /usr/local to the state it was in at stage (5) if necessary 
       (ie. look at any differences between /tmp/local-files.{before,after})

   12) Repeat from stage (5) until you get a clean install and deinstall. You may
       or may not need to 'make clean' and rebuild during this cycle depending on
       what you change.

   13) Build a package from your port, and test that pkg_add(1) and pkg_delete(1)
       will similarly install and remove the port cleanly.  (One gotcha is that
       pkgs cannot generate empty directories, so it may be necessary to add 
       zero-length .placeholder files)

   14) 'make clean' in the port.  Remove any backup copies of files or other detritus.
       Run portlint(1) and fix up anything it makes a valid complaint about.

   15) Create a diff against the original copy of the port:

         # cd ..
         # diff -Nur /usr/ports/science/paraview/ paraview/ > paraview.diff

       *Read* *through* the diff file as a sanity check.  It's surprising how
       frequently you'll find a stray copy of an editor backup file has slipped
       through at stage (14).

   16) Create a problem report, incorporating your diff:

         # send-pr -a paraview.diff -P > paraview.pr
         # emacs paraview.pr
         # send-pr -f paraview.pr 

       When editing the PR, it helps the committers if you can list out any
       added, deleted or renamed files from the port itself.  I like to provide
       links to ChangeLogs or similar for the benefit of anyone who does their
       due dilligence before updating, but that's up to you.

       If you're not the port maintainer, then set the PR as a 'change-request'
       If there is a listed maintainer, you can CC them in the PR, but the ports
       automation will send them e-mail anyhow.  If this is an update to close a
       publicised security hole, then CC'ing secteam at freebsd.org is helpful.  (If
       it's not a /publicised/ security hole, then it's better to contact the port
       maintainer or secteam@ privately rather than submitting an update through
       a public channel like the FreeBSD PR system).
       
    You should receive an acknowledgement from Gnats with a PR number in about 15
    minutes.  A committer will generally take the PR within a few hours and add it
    to their tinderbox queue for testing.  If they are happy and everything works
    satisfactorily, then the update will generally be committed within about a week.

    Do this successfully enough times with unmaintained ports, and you will likely be 
    offered maintainership when you submit updates.  Volunteer to maintain a number
    of ports and keep supplying a good stream of correct updates and you're well on
    the slippery slope towards having a commit bit and an @freebsd.org  address
    thrust upon you...

	Cheers,

	Matthew

-- 
Dr Matthew J Seaman MA, D.Phil.                   7 Priory Courtyard
                                                  Flat 3
PGP: http://www.infracaninophile.co.uk/pgpkey     Ramsgate
                                                  Kent, CT11 9PW

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 259 bytes
Desc: OpenPGP digital signature
Url : http://lists.freebsd.org/pipermail/freebsd-ports/attachments/20090818/547de110/signature.pgp