Skip to content

Expectations and Examples

Jody Garnett edited this page Jul 29, 2014 · 1 revision

This page was created during the [GeoServer Provenance Review](GeoServer Provenance Review) to assist during the manual review process. It illustrates common mistakes found during the review of the GeoServer codebase.

Expected Header

Here is what we are expecting for a header:

/* Copyright (c) 2005-2013 OpenPlans - www.openplans.org. All rights reserved.
 * This code is licensed under the GPL 2.0 license, available at the root
 * application directory.
 */

What can we tell:

  • Contributor signed a code contribution agreement
  • File was created in 2005
  • File was last modified in 2013
  • The code will pass out of copyright in 2133 (ie 120 years)
  • Just because we run a compiler past it does not automatically mean we update the date
  • Same probably goes for a pretty printer or search and replace (we are interested in protecting human authors here)

Example of a Normal File

Here is what most of the headers look like:

/* Copyright (c) 2001 - 2011 TOPP - www.openplans.org. All rights reserved.
 * This code is licensed under the GPL 2.0 license, available at the root
 * application directory.
 */

What can we tell:

  • Contributor signed a code contribution agreement
  • The default header for GeoServer indicated © 2001 (so if you really care about start date you could double check the file history)
  • The header was last modified (by hand) in 2011
  • The name of the organisation has changed

Result:

/* Copyright (c) 2001 - 2011 OpenPlans - www.openplans.org. All rights reserved.
 * This code is licensed under the GPL 2.0 license, available at the root
 * application directory.
 */

Example of a New File

Here is what headers for a newly created file look like:

/* Copyright (c) 2012 TOPP - www.openplans.org. All rights reserved.
 * This code is licensed under the GPL 2.0 license, available at the root
 * application directory.
 */

What can we tell:

  • Contributor signed a code contribution agreement
  • This file has just been added to the code base in 2012 year
  • The name of the organisation has changed to OpenPlans

Result

/* Copyright (c) 2012 OpenPlans - www.openplans.org. All rights reserved.
 * This code is licensed under the GPL 2.0 license, available at the root
 * application directory.
 */

Example of Apache License

/*
 * The Apache Software License, Version 1.1
 *
 *
 * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Xerces" and "Apache Software Foundation" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact [email protected].
 *
 * 5. Products derived from this software may not be called "Apache",
 *    nor may "Apache" appear in their name, without prior written
 *    permission of the Apache Software Foundation.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation and was
 * originally based on software copyright (c) 1999, International
 * Business Machines, Inc., http://www.apache.org.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 */

//package org.apache.xerces.impl.io;

What we can tell:

  • File was provided under apache license
  • Created in 2000, updated in 2002 (so we have a copy of an old file here!)
  • License terms are fairly clear

Actions:

  • Double check we have reproduced the license (note we are not changing the license)
  • Double check we have acknowledged our software contains some apache code as requested

Example of LGPL from GeoTools

    package org.geotools.referencing.operation.projection;

    import org.geotools.metadata.iso.citation.Citations;
    import org.geotools.referencing.NamedIdentifier;
    import org.opengis.parameter.ParameterDescriptor;
    import org.opengis.parameter.ParameterDescriptorGroup;
    import org.opengis.parameter.ParameterNotFoundException;
    import org.opengis.parameter.ParameterValueGroup;
    import org.opengis.referencing.operation.CylindricalProjection;
    import org.opengis.referencing.operation.MathTransform;

    /**
     * Mercator 1SP variation used by Google, which basically requires to accept lat/lon values
     * as spherical coordinates, that is, avoiding to do any conversion from ellipsoid to the sphere.
     * @author Andrea Aime
     * @deprecated Since GeoTools 2.4.0 there is no need to use this custom projection anymore, use 
     *             the WKT definition suggested in {@link http://jira.codehaus.org/browse/GEOT-1511}
     *             instead
     */
    public class Mercator1SPGoogle extends Mercator {

What we can tell:

  • No header - but package name and comment indicate this was from GeoTools
  • GeoTools 2.4.0 gives us an idea of when this was last modified

Actions:

  • Raise an issue: [https://jira.codehaus.org/browse/GEOS-5457]
  • Update the header to indicate we are providing this under GPL (default action for a missing header)
  • GeoServer and GeoTools have a standing arrangement, as a GeoServer contributor we need to send an email asking for a file to the geotools-devel email list. This is acknowledged by a GeoTools PMC member (or an alternate suggestion made).
  • When reusing code from any project we record where we got it from in the header (and under what license if necessary):
    /* Copyright (c) 2004-2012 OpenPlans - www.openplans.org. All rights reserved.
     *           (c) 2003-2004 Open Source Geospatial Foundation (LGPL)
     * This code is licensed under the GPL 2.0 license, available at the root
     * application directory.
     */

For additional examples see the geotools project .

Example of Generated File

Some of the Java files are generated as part of the build.

/* Generated By:JJTree: Do not edit this line. ASTAxisId.java */
package org.geoserver.wcs.kvp.rangesubset;

What we can tell:

  • In this case the original grammar file is considered the source code (and should have a header comment)
  • We do not expect the individually generated files to have GPL headers.

Example from Tutorial or Magazine Code

Some of the code has been pulled from example code, as such the license story needs to be checked a bit differently (this is common for code examples).

  • GZIPResponseStream and related files are based on a code example

https://jira.codehaus.org/browse/GEOS-5460

    /*
     * Copyright 2003 Jayson Falkner ([email protected])
     * This code is from "Servlets and JavaServer pages; the J2EE Web Tier",
     * http://www.jspbook.com. You may freely use the code both commercially
     * and non-commercially. If you like the code, please pick up a copy of
     * the book and help support the authors, development of more free code,
     * and the JSP/Servlet/J2EE community.
     *
     * Modified by David Winslow <[email protected]>
     */

Here is what we can tell:

  • The code can be used freely (yay!) and commercially (geoserver based projects), so we are in keeping with the spirit of the header
  • We can update the header to document our use of the file, but we are not changing the license

Result:

    /*
     * Copyright (c) 2007 - 2013 OpenPlans - www.openplans.org. All rights reserved.
     * Copyright 2003 Jayson Falkner ([email protected])

     * This code is from "Servlets and JavaServer pages; the J2EE Web Tier",
     * http://www.jspbook.com. You may freely use the code both commercially
     * and non-commercially. If you like the code, please pick up a copy of
     * the book and help support the authors, development of more free code,
     * and the JSP/Servlet/J2EE community.
     *
     * Modified by David Winslow <[email protected]> on 2007-12-13.
     */

Example using Version Control History to Recover Authorship

BEFORE

        /*
         * This code is free software; you can redistribute it and/or
         * modify it under the terms of the GNU Lesser General Public 
         * License as published by the Free Software Foundation; either 
         * version 2.1 of the License, or (at your option) any later version.
         *
         * This code 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 Lesser General Public License for more details.
         *
         * You should have received a copy of the GNU Lesser General Public 
         * License along with this program; if not, write to the Free 
         * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, 
         * MA  02111-1307, USA.
         */

What we can tell:

  • Header is not telling us who contributed the file, checking github history indicates it was Andrea Aime in 2011
  • Header indicates Andrea has provided us this file as LGPL (perhaps not on purpose?)
  • Further inspection (in the class javadoc) shows this code Copyright 1999~~2001 by Eric Albert, and can be used as long as we preservice the following comment:
     * This code is Copyright 1999-2001 by Eric Albert ([email protected]) 
     * and may be redistributed or modified in any form without restrictions as 
     * long as the portion of this comment from this paragraph through the end of 
     * the comment is not removed.  The author requests that he be notified of 
     * any application, applet, or other binary that makes use of this code, but 
     * that's more out of curiosity than anything and is not required.  This 
     * software includes no warranty.  The author is not repsonsible for any loss 
     * of data or functionality or any adverse or unexpected effects of using 
     * this software.
     * <p>
     * Credits:
     * <br>Steven Spencer, JavaWorld magazine 
     * (<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip66.html">
     * Java Tip 66</a>)
     * <br>Thanks also to Ron B. Yeh, Eric Shapiro, Ben Engber, Paul Teitlebaum, 
     * Andrea Cantatore,
     * Larry Barowski, Trevor Bedzek, Frank Miedrich, and Ron Rabakukk
     *
     * @author Eric Albert (<a href="mailto:[email protected]">
     * [email protected]</a>)
     * @version 1.4b1 (Released June 20, 2001)
     *
     * @author <a href="mailto:[email protected]">Jacob Dreyer</a>
     * Added methods to the API and adjusted the linux version slightly.
     */

Actions:

  • Raise an issue: GEOS-5456

  • Contact the Author to clarify their intensions about LGPL

  • In this case Andrea has signed a code contribution agreement, and LGPL is compatible with GPL

  • So we can probably go ahead and change the header to:

      /* Copyright (c) 2011-2012 OpenPlans - www.openplans.org. All rights reserved.
       *           (c) 1999-2001 Eric Albert ([email protected]) 
       *
       * This code is licensed under the GPL 2.0 license, available at the root
       * application directory.
       * 
       * This code is Copyright 1999-2001 by Eric Albert ([email protected]) 
       * and may be redistributed or modified in any form without restrictions as 
       * long as the portion of this comment from this paragraph through the end of 
       * the comment is not removed.  The author requests that he be notified of 
       * any application, applet, or other binary that makes use of this code, but 
       * that's more out of curiosity than anything and is not required.  This 
       * software includes no warranty.  The author is not repsonsible for any loss 
       * of data or functionality or any adverse or unexpected effects of using 
       * this software.
       * <p>
       * Credits:
       * <br>Steven Spencer, JavaWorld magazine 
       * (<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip66.html">
       * Java Tip 66</a>)
       * <br>Thanks also to Ron B. Yeh, Eric Shapiro, Ben Engber, Paul Teitlebaum, 
       * Andrea Cantatore,
       * Larry Barowski, Trevor Bedzek, Frank Miedrich, and Ron Rabakukk
       */
    
Clone this wiki locally