Metadata-Version: 1.1
Name: update-copyright
Version: 0.5
Summary: Automatically update copyright blurbs in versioned source.
Home-page: http://blog.tremily.us/posts/update-copyright/
Author: W. Trevor King
Author-email: wking@tremily.us
License: GNU General Public License (GPL)
Download-URL: http://git.tremily.us/?p=update-copyright.git;a=snapshot;h=v0.5;sf=tgz
Description: .. -*- 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} comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.
          long: This file is part of {project}.
        
            {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.
        
            {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.
        
            You should have received a copy of the GNU General Public License along with {project}.  If not, see <http://www.gnu.org/licenses/>.
        
        Options
        -------
        
        project/name
          A string naming your project.  Replaces ``{project}`` 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 <jdoe@a.com> | Jane Smith <jsmith@b.net>
        
          [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 <jdoe@a.com>: John Doe | jdoe | J. Doe <j@doe.net>
        
        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
        
Platform: all
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Software Development
Provides: update_copyright
Provides: update_copyright.vcs
