YAML Legal Information Blocks
=============================

eZ uses blocks of YAML code inside of comments in source code to make
the legal information for a given file easily machine readable.

The blocks should be placed at the end of source code files to ensure
that changes in license info don't cause troubles with diffs (esp. for
the case of adding a machine-readable legal info block to a third-party
file.)

If eZ holds complete copyright on the source file in question, the YAML
block looks as follows:

  /* BEGIN LEGAL INFORMATION BLOCK
  --- 
  SOFTWARE NAME: eZ Publish
  SOFTWARE RELEASE: x.x.x
  COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
  SOFTWARE LICENSE: GNU General Public License v2.0
  ... 
  END LEGAL INFORMATION BLOCK */

However, for files which already contains a YAML header (this goes for
most files in eZ publish), this extra YAML block at the bottom is not 
needed and should be avoided

If the file includes work that is copyright by eZ and work that is
licensed to eZ under the eZCLA, then the YAML block should be of the
form that follows:

  /* BEGIN LEGAL INFORMATION BLOCK
  --- 
  SOFTWARE NAME: eZ Publish
  SOFTWARE RELEASE: x.x.x
  COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
  SOFTWARE LICENSE: GNU General Public License v2.0
  CONTRIBUTORS: {J. Random: j@example.com, A. L. Ice: }
  ... 
  END LEGAL INFORMATION BLOCK */

again, If the file already includes a YAML header, the CONTRIBUTOR list
should instead be added to the existing header instead of adding a new
YAML block at the bottom. Example:

// ## BEGIN COPYRIGHT, LICENSE AND WARRANTY NOTICE ##
// SOFTWARE NAME: eZ publish
// SOFTWARE RELEASE: 3.8.x
// COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
// SOFTWARE LICENSE: GNU General Public License v2.0
// CONTRIBUTORS: {J. Random: j@example.com, A. L. Ice: }
// NOTICE: >
//   This program is free software; you can redistribute it and/or
//   modify it under the terms of version 2.0  of the GNU General
//   Public License as published by the Free Software Foundation.
//
//   This program 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 version 2.0 of the GNU General
//   Public License along with this program; if not, write to the Free
//   Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
//   MA 02110-1301, USA.
//
//
// ## END COPYRIGHT, LICENSE AND WARRANTY NOTICE ##

Since this header is replaced during buildtime (by either a GPL or eZPUL
header, it is an option to only support adding CONTRIBUTORS to the
bottom of the block like this
// ## BEGIN COPYRIGHT, LICENSE AND WARRANTY NOTICE ##
// SOFTWARE NAME: eZ publish
// SOFTWARE RELEASE: 3.8.x
// COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
// SOFTWARE LICENSE: GNU General Public License v2.0
// NOTICE: >
//   This program is free software; you can redistribute it and/or
//   modify it under the terms of version 2.0  of the GNU General
//   Public License as published by the Free Software Foundation.
//
//   This program 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 version 2.0 of the GNU General
//   Public License along with this program; if not, write to the Free
//   Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
//   MA 02110-1301, USA.
//
//
// ## END COPYRIGHT, LICENSE AND WARRANTY NOTICE ##
// CONTRIBUTORS: {J. Random: j@example.com, A. L. Ice: }

Adding this information to a exisisting header instead of adding a new
YAML block at the end of the files goes for all examples in this spec.
  
If the file is completely written by a contributor, then the block would
look something like:

  /* BEGIN LEGAL INFORMATION BLOCK
  --- 
  SOFTWARE NAME: eZ Publish
  SOFTWARE RELEASE: x.x.x
  COPYRIGHT NOTICE: Copyright (C) 2006 C. O. Ntributor
  SOFTWARE LICENSE: GNU General Public License v2.0
  CONTRIBUTORS: {C. O. Ntributor: c.o.ntributor@example.com}
  ... 
  END LEGAL INFORMATION BLOCK */

If the file is taken from third party software, it would look something
like:

  /* BEGIN LEGAL INFORMATION BLOCK
  --- 
  SOFTWARE NAME: Random Library
  SOFTWARE RELEASE: x.x.x
  COPYRIGHT NOTICE: Copyright (C) 1998-2004 A. U. Thor
  SOFTWARE LICENSE: New BSD License
  ... 
  END LEGAL INFORMATION BLOCK */

Alternately, if dealing with a piece of third party software that
contains many files and that lives in its own directory, we can add a
file called LICENSE.YAML that follows the same form as the following
code:

  --- 
  SOFTWARE NAME: Random Library
  SOFTWARE RELEASE: x.x.x
  COPYRIGHT NOTICE: Copyright (C) 1998-2004 A. U. Thor, C. O. N. \
                    Tributor and others.
  SOFTWARE LICENSE: New BSD License
  ...