eddy / perl589delta Goto Github PK

Welcome to the perl589delta project!

This project exists to distribute the work involved with writing
the perl589delta.pod file for the 5.8.9 release of Perl.

Getting involved is easy.  You volunteer to handle a month's worth of
changelog (a chunk), and then write the relevant sections of the
perldelta for those changes, or as much as you can given the time you
have available.

If you're not a Perl-guts ninja, and aren't sure if you're able
to help, read the micro-helpers HOWTO at:

  http://github.com/pfenwick/perl589delta/tree/master/Micro-helpers-HOWTO.txt

If you want to dive in, then read on!

This project uses git for change control.  You don't have to use
git to be a contributor, but it's encouraged.

The procedure for volunteering to take a chunk of work is:

    * To help co-ordinate efforts between volunteers, you are
      encouraged to join the perl589delta mailing list at
      
          http://groups.google.com/group/perl589delta

    * If you want to work with the full git environment, register
      for an account on http://github.com/ .

    * Grab the latest copy of the repository.  With git you can
      use:

        git clone git://github.com/pfenwick/perl589delta.git 

      If you've got your commit-bit already, you can use:

        git clone [email protected]:pfenwick/perl589delta.git

      If you're working without git, you can download the master
      branch files at:

        http://github.com/pfenwick/perl589delta/tarball/master

    * Look at the Volunteers.txt file and select a free month.
      Send a note to [email protected] saying which
      month you're going to work on.  You'll be given a commit bit, 
      but you can start work without it.

    * Do all your work on the branch with your chunk number.  You
      can switch to your branch and make sure it's up-to-date with:

        git checkout -b 1970-01 origin/1970-01
        git merge master
        git push origin 1970-01

      Replace 1970-01 with your chunk ID.  The 'git merge master'
      will make sure you've got the latest perl589delta.pod
      and tools.  The push line will make sure your changes go
      back to the main repo.

      If that fails, or if you're using a sub-chunk (something
      that ends with a letter), then you'll need to make your
      own branch and push it back to the mothership repository:

            git checkout master
            git pull
            git branch 2007-02-x
            git push origin 2007-02-x

      If you're not using git, or don't want to worry about the branches,
      just make changes normally and send patches to
      [email protected], and they'll get applied to your branch.
      It will help if you put [PATCH] in the subject line.

    * The files in the split/ directory are the Changes file
      already broken down by month.  You'll probably find them
      much more useful than trying to work through the Changes
      file itself.

    * Work on your branch, not on the master.  The master branch
      is ONLY for completed chunks, and for shared resources such
      as the Volunteers file and helper programs.

    * If anything is too hard, simply note them (including the
      patch number) in the TODO file in your branch.  It's okay
      to skip changes; you're encouraged to do so if it keeps
      you productive.

    * Alternatively, if most of the changes are difficult to
      comprehend, feel free to just document the changes that
      do make sense.  To track these, the recommended method
      is to remove the completed changes from your split file
      to prevent duplicate work later on.

    * When your chunk is completed, or when you've done as much
      as you'd like, e-mail [email protected]
      to arrange for it to be merged into the master branch.
      Please be sure to note if your work is completed, if there
      are items in the TODO file, if you only got up to a certain 
      spot, or if you've been removing the completed items from
      the split file.

    * Feel warm and fuzzy about your contributions to Perl!

    * If you have any questions, don't hesitate to e-mail
      the group on [email protected] for assistance,
      or ask on #p5p on irc.perl.org.

= TOOLS AND RESOURCES =

* http://public.activestate.com/cgi-bin/perlbrowse

The Perl Repository browser.  If you need to look up what a particular
patch entails, you can do it here.

* http://github.com/feeds/pfenwick/commits/perl589delta/master

This is a feed for watching the progress on the main branch.

* #p5p on irc.perl.org

This is the IRC channel where many of the Perl 5 porters hang
out.  They've agreed to make themselves available to volunteers of
the Perl 5.8.9 delta effort.  If you need assistance, especially
about what a given patch does or needs, don't hesitate to ask on #p5p.

* bin/get-changes 

Downloads the latest Changes file.  You probably won't need this,
unless you're working on super recent chunks.

* bin/split-changes

Splits the changes file up by months and puts the results in the
splits/ directory.  You probably won't need this either unless
you're working on super recent chunks.