Skip to content

Templates

Jump to bottom Edit New page
klemmj edited this page Mar 27, 2013 · 10 revisions

Introduction

This page provides templates for informational notices to be added to project content during migration.

For the below please fill out the <Fields> as follows:

  • Project: Name of Project and any important links to documentation, mailing lists, issue tracking, and others.
  • Component: For each and every library or subsystem that this product depends, identify the component name, the license it is using and a link to find that component.
  • Copyrights: Please use the initial year of development for the year and the institutes that developed the code as the copyright owner and not the NCI.

Project Notice Files

Every project needs a LICENSE, NOTICE, and README file.

LICENSE

The "LICENSE" file contains the terms of the BSD 3-Clause License:

Copyright (c) <YEAR>, <OWNER>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.

  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.

  Neither the name of the National Cancer Institute nor <OWNER> nor the names of its contributors
  may be used to endorse or promote products derived from this software
  without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS 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 COPYRIGHT HOLDER OR 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.

Place a copy of the LICENSE file in the top-level directory of every branch of the project converted from Subversion. The file may be optionally named "LICENSE.txt".

LICENSE URL

Create a gh-pages branch in the Github repository and populate it with a copy of the LICENSE.txt file such that a URL of the form:

http://ncip.github.com/<GitHub-repo-name>/LICENSE.txt

links to the file. For example:

http://ncip.github.com/c3pr/LICENSE.txt

This URL will be referenced by Source Code Headers below.

To populate the gh-pages branch see the below Tip: Github Pages.

NOTICE

The NOTICE file provides details about the origins of the project content and the credit for it:

<PROJECTNAME>
Copyright <INITIALYEAR> <COPYRIGHTHOLDERS>

This project is distributed under the BSD 3-Clause License.
Please see LICENSE file for details.


This project was developed as part of the NCI caBIG initiative.

In 2013, as part of the National Cancer Informatics Program (NCIP) Open Development Initiative,
the <PROJECT NAME> source code was migrated to GitHub to allow further development by the broader
community.

[INSERT HERE Any historical notes about development teams, contributors and
major changes to the project (no more than a few paragraphs).]


--- [ OPTIONAL SECTION ] ----

This project includes as sub-components other projects that are copyrighted by
third parties and that distributed under various licenses. Please find a
summary in the list below:

1) Component #1:
   Copyright Holder
   License

2) Component #2:
   Copyright Holder
   License

3) Component #3:
   Copyright Holder
   License

...

Place a copy of the NOTICE file next to every copy of the LICENSE file. Optionally leave it out of the gh-pages branch as only the LICENSE file is needed there.

README

The project README file provides a launching point for newcomers:

Welcome to the <PROJECTNAME> Project!
=====================================

<PROJECTNAME> is an Open Source project the provides the functionalities of <...>
It is written in <PROGRAMMING LANGUAGE> using <BASED_TECHNOLOGIES>.
The goal of <PROJECTNAME> is to <...>.

<PROJECTNAME> is distributed under the BSD 3-Clause License.
Please see the NOTICE and LICENSE files for details.

You will find more details about <PROJECTNAME> in the following links:

    *  Issue Tracker: <ISSUE_TRACKER_URL>
    *  Documentation wiki or website:  <DOCUMENTATION_PAGES_URL>
    *  Documentation repository:  <DOCUMENTATION_REPOSITORY_URL>
    *  Data repository:  <DATA_REPOSITORY_URL>
    *  Code repository:  https://github.com/NCIP/<PROJECTNAME>
    *  Mailing list:  <MAILING_LIST_SUBSCRIPTION_PAGE_URL>

A hosted instance of <PROJECTNAME> is publicly available at:

<INSTANCE_URL>

Please join us in further developing and improving <PROJECTNAME>.

Place a copy of the README file in the master branch of the repository on Github. Github will render the content of the README file on its top-level page for the project repository. The file may be optionally named "README.txt", "README.md", or "README.rst" depending on the markup language used.

If the project has separate Documents and/or Data repositories add a bullet to the above template to link to them. Furthermore, each repository will have its own README.

README for Documents

If a project has a separate documents repository it should also have a README for Github to render. The documents repository README may simply refer to the main project repository:

<PROJECTNAME> Documents
=======================

This repository holds documents for the <PROJECTNAME> project.
See https://github.com/NCIP/<PROJECTNAME> for further information.

Of course any other relevant information about the purpose of the documents repository may be added.

README for Data

If a project has a separate data repository it should also have a README for Github to render. The data repository README may simply refer to the main project repository:

<PROJECTNAME> Data Files
========================

This repository holds data files for the <PROJECTNAME> project.
See https://github.com/NCIP/<PROJECTNAME> for further information.

Of course any other relevant information about the purpose of the data repository may be added.

Source Code Headers

Add a notice header comment to every source code file in the project. Use an appropriate comment syntax for the language of the file, but ensure that the following rectangle of text appears inside it:

Copyright <COPYRIGHT_HOLDER_NAME>

Distributed under the OSI-approved BSD 3-Clause License.
See http://ncip.github.com/<GITHUB_REPO_NAME>/LICENSE.txt for details.

By naming the license explicitly we allow people familiar with it to know the terms immediately. By referencing a fixed URL instead of an "accompanying file" the reference remains valid even when someone copies a file to distribute individually. It also provides an unambiguous way to find the license terms even if the URL goes away one day.

If there is more than one Copyright holder then just repeat the line:

Copyright <holder1>
Copyright <holder2>

or list multiple holders on one line:

Copyright <holder1> and <holder2>

Note that the Copyright line does not list any years. The years go in the NOTICE and LICENSE files. They can optionally go in the source code headers but in practice the headers are rarely maintained properly (it should be updated separately as each file is modified).

The following subsections show header templates formatted for several source code file types along with an example of each template expanded for a specific project.

Optionally apply the headers using the below Tip: Script Source Code Headers.

Note

Source code header notices have no legal meaning. When one takes a file from somewhere one is responsible to hunt down the copyright and license terms for it. These notices only serve as a convenience to help users learn this information. In the modern world version control systems can tell people the date on which each line in the file was last modified, so there is no need for that information to be repeated at the top of the source in the copyright notice. (Ideally when someone copies the file outside the project s/he will add the year range covered by the original project, but that is not our problem.) Some people will claim that all years and names should appear in each file in order to "give credit", but that is a separate issue from license notices.

Java Code Header

Template:

//============================================================================
// Copyright <COPYRIGHT_HOLDER_NAME>
//
// Distributed under the OSI-approved BSD 3-Clause License.
// See http://ncip.github.com/<GITHUB_REPO_NAME>/LICENSE.txt for details.
//============================================================================

Example:

//============================================================================
// Copyright Duke Comprehensive Cancer Center and SemanticBits
//
// Distributed under the OSI-approved BSD 3-Clause License.
// See http://ncip.github.com/c3pr/LICENSE.txt for details.
//============================================================================

XML Code Header

Template:

<!--
  Copyright <COPYRIGHT_HOLDER_NAME>

  Distributed under the OSI-approved BSD 3-Clause License.
  See http://ncip.github.com/<GITHUB_REPO_NAME>/LICENSE.txt for details.
-->

Example:

<!--
  Copyright Duke Comprehensive Cancer Center and SemanticBits

  Distributed under the OSI-approved BSD 3-Clause License.
  See http://ncip.github.com/c3pr/LICENSE.txt for details.
-->

Properties Code Header

Template:

#-----------------------------------------------------------------------------
# Copyright <COPYRIGHT_HOLDER_NAME>
#
# Distributed under the OSI-approved BSD 3-Clause License.
# See http://ncip.github.com/<GITHUB_REPO_NAME>/LICENSE.txt for details.
#-----------------------------------------------------------------------------

Example:

#-----------------------------------------------------------------------------
# Copyright Duke Comprehensive Cancer Center and SemanticBits
#
# Distributed under the OSI-approved BSD 3-Clause License.
# See http://ncip.github.com/c3pr/LICENSE.txt for details.
#-----------------------------------------------------------------------------

JSP and TAG Code Header

Template:

<%--
  Copyright <COPYRIGHT_HOLDER_NAME>

  Distributed under the OSI-approved BSD 3-Clause License.
  See http://ncip.github.com/<GITHUB_REPO_NAME>/LICENSE.txt for details.
--%>

Example:

<%--
  Copyright Duke Comprehensive Cancer Center and SemanticBits

  Distributed under the OSI-approved BSD 3-Clause License.
  See http://ncip.github.com/c3pr/LICENSE.txt for details.
--%>

SQL and Groovy Code Header

Template:

/*
  Copyright <COPYRIGHT_HOLDER_NAME>

  Distributed under the OSI-approved BSD 3-Clause License.
  See http://ncip.github.com/<GITHUB_REPO_NAME>/LICENSE.txt for details.
*/

Example:

/*
  Copyright Duke Comprehensive Cancer Center and SemanticBits

  Distributed under the OSI-approved BSD 3-Clause License.
  See http://ncip.github.com/c3pr/LICENSE.txt for details.
*/

Tips

This section provides tips on the technical details of adding notice files and source code headers.

Tip: Github Pages

Add a disjoint gh-pages branch to a given project repository to populate content under the URL:

http://ncip.github.com/$repo

using a session such as:

$ mkdir gh-pages && cd gh-pages
$ git init
$ cp ../LICENSE.txt .
$ git add LICENSE.txt
$ git commit -m "Add LICENSE.txt"
$ git push [email protected]:NCIP/$repo.git HEAD:gh-pages

Tip: Script Source Code Headers

One may use sed to add a header to source code files while preserving a UTF-8 Byte-Order-Mark. For example, use the following bash code to add a header to Java source files:

$ find * -name '*.java' | while read f; do
  sed -i '1s|^\(\xEF\xBB\xBF\)\?|&'\
'//============================================================================\
// Copyright <COPYRIGHT_HOLDER_NAME>\
//\
// Distributed under the OSI-approved BSD 3-Clause License.\
// See http://ncip.github.com/<GITHUB_REPO_NAME>/LICENSE.txt for details.\
//============================================================================\
\
|' "$f"
done
Add a custom footer
Add a custom sidebar
Clone this wiki locally