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