pjs/tools/relic/README

            ReadMe for relic.py (a Mozilla relicensing tool)


    This script is intended to facilitate re-licensing the Mozilla source
    tree pursuant to <http://mozilla.org/MPL/>. It cannot do the full job
    automatically but handles most of the grunt work.

Table of Contents:

    The Problem
    Getting Started
    Basic Usage
    What Files are Processed
    Error Handling (--force)
    Unfinished Business
    Contributors


The Problem:

    The basic problem is that Mozilla has a lot of files. The goal is to have
    all the files (with a few minor exceptions) contain a leading license
    block that is either the MPL/GPL/LGPL tri-license or the NPL/GPL/LGPL
    tri-license. Because this was never rigorously enforced a lot of cleanup
    is necessary to correct license blocks in Mozilla's files. This script
    will traverse the given directory(s)/file(s) and fixup the leading
    license block, or give an error message explaining why it cannot. (It
    also has modes to just scan for and summarize license info.)


Getting Started:

    While 'relic.py' is probably quite portable to Windows it has not been
    tested there. There may be some hidden path-delimiter bugs. It is
    probably best to just run this script on Linux.

    To use:
    - crack the relic-<version>.tar.gz tarball in some directory
    - call './relic.py --help' to learn the basic usage
    - play with './relic.py ...' as desired.


Basic Usage:

    'relic.py' has a --help option that explains the basic usage but I'll go
    through some examples here. In our examples we will work on re-licensing
    the mozilla/js/src directory tree.

    'relic.py' has three modes.
    (1) List license info on each file processed (the default)

        $ ./relic.py mozilla/js/src/jsapi.h
        /js/src/jsapi.h
        ... npl/gpl found
        ... license block lines: 2-32
        ... original code is: Mozilla Communicator client code
        ... initially by: Original Code is Netscape Communications Corporation (1998)

    (2) Gather and dump statistics on the processed files:

        $ ./relic.py -s mozilla/js/src/jsapi.h
        Summary of Licenses in Files
        ============================
         Number  Percent License
        ------- -------- -----------
              1  100.00% npl/gpl
        ----------------------------
              1 files processed

        Licensed files with complete tri-license block: 0
        Licensed files with no 'Initial Developer...' info: 0
        Licensed files with no 'Original Code is...' info: 0
        Licensed files with improperly indented 'Contributor(s):' line(s): 0

    (3) Re-licensing the given files that need it (i.e. files with a complete
        and correct license block are changed).

        $ ./relic.py -r mozilla/js/src/jsapi.h
        mozilla/js/src/jsapi.h
        ... npl/gpl found, need to relicense
        ... original code is: Mozilla Communicator client code
        ... initially by: Original Code is Netscape Communications Corporation (1998)
        ... replacing lines 2-32 with NPL/GPL/LGPL tri-license
        ... backing up to 'mozilla/js/src/jsapi.h~0'
        ... done relicensing 'mozilla/js/src/jsapi.h'

        --------------------- Summary of Results ------------------------
        Files skipped b/c they are binary: 0
        Files skipped b/c they already had proper license: 0
        Files skipped b/c they had no license: 0
        Files re-licensed: 1
        -----------------------------------------------------------------

    If you are trying this as you read this, run the following command to see
    the changes made to jsapi.h:

        $ diff -c mozilla/js/src/jsapi.h~0 mozilla/js/src/jsapi.h


What Files are Processed:

    'relic.py' will process any files listed on the command line and will
    recursively process all files in any given directories:

        $ ./relic.py -s mozilla/js/src
        Summary of Licenses in Files
        ============================
         Number  Percent License
        ------- -------- -----------
            324   74.14% npl/gpl
             71   16.25% <none found>
             23    5.26% mpl/gpl/lgpl
              4    0.92% npl/gpl/lgpl
              4    0.92% mpl
              4    0.92% ibm
              3    0.69% mpl/gpl
              2    0.46% npl
              2    0.46% <unknown license>
        ----------------------------
            437 files processed

        Licensed files with complete tri-license block: 27
        Licensed files with no 'Initial Developer...' info: 1
        Licensed files with no 'Original Code is...' info: 27
        Licensed files with improperly indented 'Contributor(s):' line(s): 2
   
    The following files are automatically skipped:
    - CVS control directories;
    - files listed in .cvsignore files;
    - all *.s files (there usage of comment delimiters is all over the map);
    - binary files; and
    - any files included in the following global variables in relic.py:
      _g_skip_file_basenames, _g_skip_files, _g_skip_dir_basenames,
      _g_skip_dirs, _g_skip_ext.


Error Handling (--force):

    There are some situations that relic.py cannot handle. E.g., a file with
    no license block to start with, an IBM license block, a license block
    sufficiently strange enough to baffle relic.py regular expressions. In
    normal operation, when an error is encoutered on any file processing
    stops. This can be annoying, so a --force|-f option was added to force
    relic.py to continue processing files after an error with a file is
    encountered. In all modes of operation errors are summarized at the end.

        $ ./relic.py -s mozilla/extensions/transformiix/source/xml
        ERROR:relic:This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/XMLDOMUtils.h:20: ' * Keith Visco' (the --force option can be used to skip problematic files and continue processing rather than aborting)

        $ ./relic.py -sf mozilla/extensions/transformiix/source/xml
        Summary of Licenses in Files
        ============================
         Number  Percent License
        ------- -------- -----------
             24  100.00% mpl
        ----------------------------
             24 files processed

        Licensed files with complete tri-license block: 0
        Licensed files with no 'Initial Developer...' info: 16
        Licensed files with no 'Original Code is...' info: 15
        Licensed files with improperly indented 'Contributor(s):' line(s): 3


        =================== Summary of Errors ===========================
        Files with processing errors: 3
        =================================================================
        mozilla/extensions/transformiix/source/xml/XMLDOMUtils.cpp: This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/XMLDOMUtils.cpp:20: ' * Keith Visco '

        mozilla/extensions/transformiix/source/xml/XMLDOMUtils.h: This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/XMLDOMUtils.h:20: ' * Keith Visco '

        mozilla/extensions/transformiix/source/xml/parser/txXMLParser.h: This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/parser/txXMLParser.h:20: ' * Tom Kneeland'

        =================================================================
 

Unfinished Business:

    The following is a list of issues that should be sorted out before this
    should be used to start making patches to the Mozilla tree:

    - What to do for files that have no 'Initial Developer...' block?
    - What to do for files that have no 'Original Code is...' block?
    - Are there specific files or parts of the mozilla tree that should be
      skipped always, i.e. generated files, files not meant to have leading
      license blocks?
    - What to do for files with the IBM license?
    - Should *.uf be ignored (there are 87 of them in the mozilla tree)?
    - The 'ripl' and lick' scripts' "include licenses" configuration option
      is not supported in anyway by relic.py. Is it necessary? I don't see a
      useful use case.
    - test/x_thread_align_center.xml and test/abs2rel.pl are examples of
      files that are not handled correctly. In the former there is some data
      loss. In the latter the is some cruft left over.


Contributors:

    Trent Mick (TrentM@ActiveState.com) originally wrote this script,
    borrowing some from earlier attempts in the name of 'lick', 'lutils.py',
    and 'ripl' (see <http://bugzilla.mozilla.org/show_bug.cgi?id=98089>).
    If you have problems with the script please let me know and hopefully I
    can help you out.