README

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