X-Git-Url: http://git.tremily.us/?p=update-copyright.git;a=blobdiff_plain;f=README;h=5d2e3ff28f3d7e80e56aec807894e016f9e613eb;hp=8ef332dd708646244b6c2e7c41cf0784493be002;hb=acfec4340bfa7c668e6c06c208ad6ba924300f91;hpb=52267bdf2b0f60105ed9ad18836d33d995c4c89d diff --git a/README b/README index 8ef332d..5d2e3ff 100644 --- a/README +++ b/README @@ -1,4 +1,192 @@ -``update_copyright.py`` is an automatic copyright updating tool. I -wrote the original for Bugs Everywhere, but ended up copying it into a +.. -*- coding: utf-8 -*- + +``update-copyright`` is an automatic copyright updating tool. I wrote +the original for `Bugs Everywhere`_, but ended up copying it into a number of my projects. Copying is bad, so here it is, split out as its own separate project. + +Installation +============ + +Packages +-------- + +Gentoo +~~~~~~ + +I've packaged ``update-copyright`` for Gentoo_. You need layman_ and +my `wtk overlay`_. Install with:: + + # emerge -av app-portage/layman + # layman --add wtk + # emerge -av dev-util/update-copyright + +Dependencies +------------ + +``update-copyright`` is a simple package with few external +dependencies. The only external dependencies are the Python packages +behind Python-based version control systems. If you're using those +VCSs, you've already installed the packages. If you're not using +those VCSs, you don't need the packages. + +Installing by hand +------------------ + +``update-copyright`` is available as a Git_ repository:: + + $ git clone git://tremily.us/update-copyright.git + +See the homepage_ for details. To install the checkout, run the +standard:: + + $ python setup.py install + +Usage +===== + +You'll need a project that you version with one of our supported VCSs +(currently Git, Mercurial, and Bazaar, but it should be pretty easy to +add backends for other systems). You'll also need a config file +called ``.update-copyright.conf`` in your package root, which will be +parsed using Python's RawConfigParser_ (`syntax documentation`_, +interpolation is turned off). Your config file will look something +like:: + + [project] + name: update-copyright + vcs: Git + + [files] + authors: yes + files: yes + ignored: COPYING, README, .update-copyright.conf, .git* + pyfile: update_copyright/license.py + + [copyright] + short: %(project)s comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License. + long: This file is part of %(project)s. + + %(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. + + %(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. + + You should have received a copy of the GNU General Public License along with %(project)s. If not, see . + +Options +------- + +project/name + A string naming your project. Replaces ``%(project)s`` in your + copyright blurbs. +project/vcs + The name of your version control system. +files/authors + Should ``update-copyright.py`` generate an ``AUTHORS`` file? + ``yes`` or ``no``. +files/files + Should ``update-copyright.py`` update copyright blurbs in versioned + files? ``yes`` or ``no``. +files/ignored + A comma-separated list of globs matching files that should not have + copyright blurbs updated. This protects files that may accidentally + caught by the blurb update algorithm. +files/pyfile + The path of an autogenerated license module, in case your program + wants to print out its copyright/licensing information. If you + don't set this option, no license module will be generated. +copyright/short + A list of paragraphs (separated by blank lines) containing your + short copyright/license blurb. This blurb is used in the pyfile's + ``short_license`` function (see `files/pyfile`). This exists + because some programs print a short license blurb on startup, where + the full file-topping blurb may be overkill. +copyright/long + A list of paragraphs (separated by blank lines) containing your long + copyright/license blurb. This blurb is used to replace copyright + blurbs in your source files. + +Updating copyright blurbs +------------------------- + +The blurb-update algorithm looks for any lines that begin with ``# +Copyright``. These lines mark the beginning of a blurb, which +continues as long as subsequent lines begin with ``#``. The old blurb +is replaced by a new blurb, which is automatically generated from your +configured long copyright string, with author names and edit years +extracted from the VCS data for that file. + +While the above works well for languages that use ``#`` to mark +comment lines, it doesn't work for languages like C that use ``/*…*/`` +to mark comments. There blurb-update algorithm also looks for any +lines that begging with ``/* Copyright`` and replaces that line, and +subsequent lines up to one beginning with `` */``, with a new blurb. + +Because I've never seen a file with *both* trigger lines, it shouldn't +be a problem to run both against each of your versioned files. If it +is a problem for you, let me know, and we can add some configuration +options to work around the problem. + +Incomplete VCS history +---------------------- + +Sometimes files have authors or alterations not recorded in a +project's VCS history. You can use the ``author-hacks`` section to +add authors to a file, and the ``year-hacks`` section to adjust the +files original year. Author names should be pipe-separated. For +example:: + + [author-hacks] + path/to/file: John Doe | Jane Smith + + [year-hacks] + path/to/another/file: 2009 + +Add entries for as many files as you like. Paths should be relative +to your project root. Always use forward slashes (``/``) to separate +path elements. + +Aliases +------- + +Occasionally names or email addresses used when committing to the VCS +will go out of date. Some VCSs have a built-in method of dealing with +this (e.g. Git's .mailmap_). For those without such a VCS, you can +add an `aliases`` section to your config file, where the option names +are the canonical name of the ...?. For example:: + + [aliases] + John Doe : John Doe | jdoe | J. Doe + +Testing +======= + +Run the internal unit tests with:: + + $ nosetests --with-doctest --doctest-tests update_copyright + +Licence +======= + +This project is distributed under the `GNU General Public License +Version 3`_ or greater. + +Author +====== + +W. Trevor King +wking@tremily.us + + +.. _Bugs Everywhere: http://bugseverywhere.org/ +.. _Gentoo: http://www.gentoo.org/ +.. _layman: http://layman.sourceforge.net/ +.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/ +.. _Git: http://git-scm.com/ +.. _homepage: http://blog.tremily.us/posts/update-copyright/ +.. _RawConfigParser: + http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser +.. _syntax documentation: + http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure +.. _.mailmap: http://schacon.github.com/git/git-shortlog.html#_mapping_authors +.. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html