tools/relic/README

   1             ReadMe for relic.py (a Mozilla relicensing tool)
   2
   3
   4     This script is intended to facilitate re-licensing the Mozilla source
   5     tree pursuant to <http://mozilla.org/MPL/>. It cannot do the full job
   6     automatically but handles most of the grunt work.
   7
   8 Table of Contents:
   9
  10     The Problem
  11     Getting Started
  12     Basic Usage
  13     What Files are Processed
  14     Error Handling (--force)
  15     Unfinished Business
  16     Contributors
  17
  18
  19 The Problem:
  20
  21     The basic problem is that Mozilla has a lot of files. The goal is to have
  22     all the files (with a few minor exceptions) contain a leading license
  23     block that is either the MPL/GPL/LGPL tri-license or the NPL/GPL/LGPL
  24     tri-license. Because this was never rigorously enforced a lot of cleanup
  25     is necessary to correct license blocks in Mozilla's files. This script
  26     will traverse the given directory(s)/file(s) and fixup the leading
  27     license block, or give an error message explaining why it cannot. (It
  28     also has modes to just scan for and summarize license info.)
  29
  30
  31 Getting Started:
  32
  33     While 'relic.py' is probably quite portable to Windows it has not been
  34     tested there. There may be some hidden path-delimiter bugs. It is
  35     probably best to just run this script on Linux.
  36
  37     To use:
  38     - crack the relic-<version>.tar.gz tarball in some directory
  39     - call './relic.py --help' to learn the basic usage
  40     - play with './relic.py ...' as desired.
  41
  42
  43 Basic Usage:
  44
  45     'relic.py' has a --help option that explains the basic usage but I'll go
  46     through some examples here. In our examples we will work on re-licensing
  47     the mozilla/js/src directory tree.
  48
  49     'relic.py' has three modes.
  50     (1) List license info on each file processed (the default)
  51
  52         $ ./relic.py mozilla/js/src/jsapi.h
  53         /js/src/jsapi.h
  54         ... npl/gpl found
  55         ... license block lines: 2-32
  56         ... original code is: Mozilla Communicator client code
  57         ... initially by: Original Code is Netscape Communications Corporation (1998)
  58
  59     (2) Gather and dump statistics on the processed files:
  60
  61         $ ./relic.py -s mozilla/js/src/jsapi.h
  62         Summary of Licenses in Files
  63         ============================
  64          Number  Percent License
  65         ------- -------- -----------
  66               1  100.00% npl/gpl
  67         ----------------------------
  68               1 files processed
  69
  70         Licensed files with complete tri-license block: 0
  71         Licensed files with no 'Initial Developer...' info: 0
  72         Licensed files with no 'Original Code is...' info: 0
  73         Licensed files with improperly indented 'Contributor(s):' line(s): 0
  74
  75     (3) Re-licensing the given files that need it (i.e. files with a complete
  76         and correct license block are changed).
  77
  78         $ ./relic.py -r mozilla/js/src/jsapi.h
  79         mozilla/js/src/jsapi.h
  80         ... npl/gpl found, need to relicense
  81         ... original code is: Mozilla Communicator client code
  82         ... initially by: Original Code is Netscape Communications Corporation (1998)
  83         ... replacing lines 2-32 with NPL/GPL/LGPL tri-license
  84         ... backing up to 'mozilla/js/src/jsapi.h~0'
  85         ... done relicensing 'mozilla/js/src/jsapi.h'
  86
  87         --------------------- Summary of Results ------------------------
  88         Files skipped b/c they are binary: 0
  89         Files skipped b/c they already had proper license: 0
  90         Files skipped b/c they had no license: 0
  91         Files re-licensed: 1
  92         -----------------------------------------------------------------
  93
  94     If you are trying this as you read this, run the following command to see
  95     the changes made to jsapi.h:
  96
  97         $ diff -c mozilla/js/src/jsapi.h~0 mozilla/js/src/jsapi.h
  98
  99
 100 What Files are Processed:
 101
 102     'relic.py' will process any files listed on the command line and will
 103     recursively process all files in any given directories:
 104
 105         $ ./relic.py -s mozilla/js/src
 106         Summary of Licenses in Files
 107         ============================
 108          Number  Percent License
 109         ------- -------- -----------
 110             324   74.14% npl/gpl
 111              71   16.25% <none found>
 112              23    5.26% mpl/gpl/lgpl
 113               4    0.92% npl/gpl/lgpl
 114               4    0.92% mpl
 115               4    0.92% ibm
 116               3    0.69% mpl/gpl
 117               2    0.46% npl
 118               2    0.46% <unknown license>
 119         ----------------------------
 120             437 files processed
 121
 122         Licensed files with complete tri-license block: 27
 123         Licensed files with no 'Initial Developer...' info: 1
 124         Licensed files with no 'Original Code is...' info: 27
 125         Licensed files with improperly indented 'Contributor(s):' line(s): 2
 126
 127     The following files are automatically skipped:
 128     - CVS control directories;
 129     - files listed in .cvsignore files;
 130     - all *.s files (there usage of comment delimiters is all over the map);
 131     - binary files; and
 132     - any files included in the following global variables in relic.py:
 133       _g_skip_file_basenames, _g_skip_files, _g_skip_dir_basenames,
 134       _g_skip_dirs, _g_skip_ext.
 135
 136
 137 Error Handling (--force):
 138
 139     There are some situations that relic.py cannot handle. E.g., a file with
 140     no license block to start with, an IBM license block, a license block
 141     sufficiently strange enough to baffle relic.py regular expressions. In
 142     normal operation, when an error is encoutered on any file processing
 143     stops. This can be annoying, so a --force|-f option was added to force
 144     relic.py to continue processing files after an error with a file is
 145     encountered. In all modes of operation errors are summarized at the end.
 146
 147         $ ./relic.py -s mozilla/extensions/transformiix/source/xml
 148         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)
 149
 150         $ ./relic.py -sf mozilla/extensions/transformiix/source/xml
 151         Summary of Licenses in Files
 152         ============================
 153          Number  Percent License
 154         ------- -------- -----------
 155              24  100.00% mpl
 156         ----------------------------
 157              24 files processed
 158
 159         Licensed files with complete tri-license block: 0
 160         Licensed files with no 'Initial Developer...' info: 16
 161         Licensed files with no 'Original Code is...' info: 15
 162         Licensed files with improperly indented 'Contributor(s):' line(s): 3
 163
 164
 165         =================== Summary of Errors ===========================
 166         Files with processing errors: 3
 167         =================================================================
 168         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 '
 169
 170         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 '
 171
 172         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'
 173
 174         =================================================================
 175
 176
 177 Unfinished Business:
 178
 179     The following is a list of issues that should be sorted out before this
 180     should be used to start making patches to the Mozilla tree:
 181
 182     - What to do for files that have no 'Initial Developer...' block?
 183     - What to do for files that have no 'Original Code is...' block?
 184     - Are there specific files or parts of the mozilla tree that should be
 185       skipped always, i.e. generated files, files not meant to have leading
 186       license blocks?
 187     - What to do for files with the IBM license?
 188     - Should *.uf be ignored (there are 87 of them in the mozilla tree)?
 189     - The 'ripl' and lick' scripts' "include licenses" configuration option
 190       is not supported in anyway by relic.py. Is it necessary? I don't see a
 191       useful use case.
 192     - test/x_thread_align_center.xml and test/abs2rel.pl are examples of
 193       files that are not handled correctly. In the former there is some data
 194       loss. In the latter the is some cruft left over.
 195
 196
 197 Contributors:
 198
 199     Trent Mick (TrentM@ActiveState.com) originally wrote this script,
 200     borrowing some from earlier attempts in the name of 'lick', 'lutils.py',
 201     and 'ripl' (see <http://bugzilla.mozilla.org/show_bug.cgi?id=98089>).
 202     If you have problems with the script please let me know and hopefully I
 203     can help you out.
 204
 205