README

   1 ``update-copyright`` is an automatic copyright updating tool.  I wrote
   2 the original for `Bugs Everywhere`_, but ended up copying it into a
   3 number of my projects.  Copying is bad, so here it is, split out as
   4 its own separate project.
   5
   6 Installation
   7 ============
   8
   9 Packages
  10 --------
  11
  12 Gentoo
  13 ~~~~~~
  14
  15 I've packaged ``update-copyright`` for Gentoo_.  You need layman_ and
  16 my `wtk overlay`_.  Install with::
  17
  18   # emerge -av app-portage/layman
  19   # layman --add wtk
  20   # emerge -av dev-util/update-copyright
  21
  22 Dependencies
  23 ------------
  24
  25 ``update-copyright`` is a simple package with few external
  26 dependencies.  The only external dependencies are the Python packages
  27 behind Python-based version control systems.  If you're using those
  28 VCSs, you've already installed the packages.  If you're not using
  29 those VCSs, you don't need the packages.
  30
  31 Installing by hand
  32 ------------------
  33
  34 ``update-copyright`` is available as a Git_ repository::
  35
  36   $ git clone git://tremily.us/update-copyright.git
  37
  38 See the homepage_ for details.  To install the checkout, run the
  39 standard::
  40
  41   $ python setup.py install
  42
  43 Usage
  44 =====
  45
  46 You'll need a project that you version with one of our supported VCSs
  47 (currently Git, Mercurial, and Bazaar, but it should be pretty easy to
  48 add backends for other systems).  You'll also need a config file
  49 called ``.update-copyright.conf`` in your package root, which will be
  50 parsed using Python's RawConfigParser_ (`syntax documentation`_,
  51 interpolation is turned off).  Your config file will look something
  52 like::
  53
  54   [project]
  55   name: update-copyright
  56   vcs: Git
  57
  58   [files]
  59   authors: yes
  60   files: yes
  61   ignored: COPYING, README, .update-copyright.conf, .git*
  62   pyfile: update_copyright/license.py
  63
  64   [copyright]
  65   short: %(project)s comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.
  66   long: This file is part of %(project)s.
  67
  68     %(project)s is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  69
  70     %(project)s is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  71
  72     You should have received a copy of the GNU General Public License along with %(project)s.  If not, see <http://www.gnu.org/licenses/>.
  73
  74 Options
  75 -------
  76
  77 project/name
  78   A string naming your project.  Replaces ``%(project)s`` in your
  79   copyright blurbs.
  80 project/vcs
  81   The name of your version control system.
  82 files/authors
  83   Should ``update-copyright.py`` generate an ``AUTHORS`` file?
  84   ``yes`` or ``no``.
  85 files/files
  86   Should ``update-copyright.py`` update copyright blurbs in versioned
  87   files?  ``yes`` or ``no``.
  88 files/ignored
  89   A comma-separated list of globs matching files that should not have
  90   copyright blurbs updated.  This protects files that may accidentally
  91   caught by the blurb update algorithm.
  92 files/pyfile
  93   The path of an autogenerated license module, in case your program
  94   wants to print out its copyright/licensing information.  If you
  95   don't set this option, no license module will be generated.
  96 copyright/short
  97   A list of paragraphs (separated by blank lines) containing your
  98   short copyright/license blurb.  This blurb is used in the pyfile's
  99   ``short_license`` function (see `files/pyfile`).  This exists
 100   because some programs print a short license blurb on startup, where
 101   the full file-topping blurb may be overkill.
 102 copyright/long
 103   A list of paragraphs (separated by blank lines) containing your long
 104   copyright/license blurb.  This blurb is used to replace copyright
 105   blurbs in your source files.
 106
 107 Updating copyright blurbs
 108 -------------------------
 109
 110 The blurb-update algorithm looks for any lines that begin with ``#
 111 Copyright``.  These lines mark the beginning of a blurb, which
 112 continues as long as subsequent lines begin with ``#``.  The old blurb
 113 is replaced by a new blurb, which is automatically generated from your
 114 configured long copyright string, with author names and edit years
 115 extracted from the VCS data for that file.
 116
 117 While the above works well for languages that use ``#`` to mark
 118 comment lines, it doesn't work for languages like C that use ``/*…*/``
 119 to mark comments.  There blurb-update algorithm also looks for any
 120 lines that begging with ``/* Copyright`` and replaces that line, and
 121 subsequent lines up to one beginning with `` */``, with a new blurb.
 122
 123 Because I've never seen a file with *both* trigger lines, it shouldn't
 124 be a problem to run both against each of your versioned files.  If it
 125 is a problem for you, let me know, and we can add some configuration
 126 options to work around the problem.
 127
 128 Incomplete VCS history
 129 ----------------------
 130
 131 Sometimes files have authors or alterations not recorded in a
 132 project's VCS history.  You can use the ``author-hacks`` section to
 133 add authors to a file, and the ``year-hacks`` section to adjust the
 134 files original year.  Author names should be comma-separated.  For
 135 example::
 136
 137   [author-hacks]
 138   path/to/file: John Doe <jdoe@a.com>, Jane Smith <jsmith@b.net>
 139
 140   [year-hacks]
 141   path/to/another/file: 2009
 142
 143 Add entries for as many files as you like.  Paths should be relative
 144 to your project root.  Always use forward slashes (``/``) to separate
 145 path elements.
 146
 147 Aliases
 148 -------
 149
 150 Occasionally names or email addresses used when committing to the VCS
 151 will go out of date.  Some VCSs have a built-in method of dealing with
 152 this (e.g. Git's .mailmap_).  For those without such a VCS, you can
 153 add an `aliases`` section to your config file, where the option names
 154 are the canonical name of the ...?.  For example::
 155
 156   [aliases]
 157   John Doe <jdoe@a.com>: John Doe, jdoe, J. Doe <j@doe.net>
 158
 159 Testing
 160 =======
 161
 162 Run the internal unit tests with::
 163
 164   $ nosetests --with-doctest --doctest-tests update_copyright
 165
 166 Licence
 167 =======
 168
 169 This project is distributed under the `GNU General Public License
 170 Version 3`_ or greater.
 171
 172 Author
 173 ======
 174
 175 W. Trevor King
 176 wking@drexel.edu
 177
 178
 179 .. _Bugs Everywhere: http://bugseverywhere.org/
 180 .. _Gentoo: http://www.gentoo.org/
 181 .. _layman: http://layman.sourceforge.net/
 182 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 183 .. _Git: http://git-scm.com/
 184 .. _homepage: http://blog.tremily.us/posts/update-copyright/
 185 .. _RawConfigParser:
 186   http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser
 187 .. _syntax documentation:
 188   http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure
 189 .. _.mailmap: http://schacon.github.com/git/git-shortlog.html#_mapping_authors
 190 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html