-
Notifications
You must be signed in to change notification settings - Fork 7
Templates
Table of Contents
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.
Every project needs a LICENSE, NOTICE, README, and CONTRIBUTING file.
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".
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.
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 <EXTERNAL-COPYRIGHT-HOLDER-1> Distributed under <EXTERNAL-LICENSE-1> 2) Component #2: Copyright <EXTERNAL-COPYRIGHT-HOLDER-2> Distributed under <EXTERNAL-LICENSE-2> 3) Component #3: Copyright <EXTERNAL-COPYRIGHT-HOLDER-3> Distributed under <EXTERNAL-LICENSE-3> ...
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.
If the project distributes third-party code, place any notices required by its license(s) in the bottom section of the NOTICE file. For example, see these NOTICE files:
- The Apache HTTP Server NOTICE file
- The Insight Toolkit NOTICE file
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:
* <PROJECTNAME_HOME_URL>
* <MAILING_LIST_SUBSCRIPTION_PAGE_URL>
* <ISSUE_TRACKER_URL>
* <DOCUMENTATION_PAGES_URL>
* https://github.com/NCIP/<PROJECTNAME>
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.
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.
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.
The CONTRIBUTING file provides guidelines to contributors:
=================
How to Contribute
=================
We welcome community contributions to the <PROJECTNAME> project.
Your contributions back to this repository will allow the broader
research community to benefit from your work and will allow your
enhancements to be integrated with those of others. There are a few
guidelines that we ask contributors to follow so that we can have a
chance of keeping on top of things.
---------------
Getting Started
---------------
* Make sure you have a `GitHub Account`_.
* Fork the repository on GitHub to publish any proposed changes
.. If the project uses an issue tracker, use the next bullet.
Otherwise, remove the next bullet. Delete this note either way.
* Submit a ticket for your issue at <ISSUE_TRACKER_URL>,
assuming one does not already exist.
- <INSERT INSTRUCTIONS FOR GETTING AN ISSUE TRACKER ACCOUNT>
- Clearly describe the issue including steps to reproduce when it is a bug.
- Make sure you fill in the earliest version that you know has the issue.
.. _`GitHub Account`: https://github.com/signup/free
--------------
Making Changes
--------------
* Create a topic branch from where you want to base your work.
- This is usually the master branch.
- Only target release branches if you are certain your fix must be
on that branch.
- To quickly create a topic branch based on master::
git checkout -b fix/master/my_contribution master
Please avoid working directly on the master branch.
* Make commits of logical units.
* Please provide tests and documentation with your changes.
* Check for unnecessary whitespace with ``git diff --check`` before committing.
* Follow the `NCIP Good Practices for Commit Messages`_.
Start with a one-line summary followed by a blank line followed by a
detailed free-form description.
.. _`NCIP Good Practices for Commit Messages`: https://github.com/NCIP/ncip.github.com/wiki/Good-Practices#wiki-commit-messages
------------------
Submitting Changes
------------------
* In general, we require that the OSI-approved `BSD 3-Clause License`_
be applied to code contributions. There may be cases, however, that
warrant the use of an alternate OSI-approved license and we will
evaluate this situations case-by-case.
* Push your changes to a topic branch in your fork of the repository.
* Submit a pull request to the repository in the NCIP organization.
.. If the project uses an issue tracker, use the next bullet.
Otherwise, remove the next bullet. Delete this note either way.
* Update your <ISSUE_TRACKER_NAME> ticket to mark that you have submitted
code and are ready for it to be reviewed.
- Include a link to the pull request in the ticket
.. _`BSD 3-Clause License`: http://opensource.org/licenses/BSD-3-Clause
--------------------
Additional Resources
--------------------
For help learning Git and Github, see the `NCIP Learning Resources`_.
.. _`NCIP Learning Resources`: https://github.com/NCIP/ncip.github.com/wiki/Learning-Resources
Place a copy of the above in a CONTRIBUTING.rst file in the
master branch of the repository on Github. When a contributor
creates a new Github Pull-Request Github will show a link to the
file as documented by the the Github Contributing Guidelines blog
post.
The file may be optionally named CONTRIBUTING,
CONTRIBUTING.txt, CONTRIBUTING.md, or CONTRIBUTING.rst
depending on the markup language used. The above template is meant
for use as .rst.
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.
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. //============================================================================
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. //============================================================================
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. -->
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. #-----------------------------------------------------------------------------
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. #-----------------------------------------------------------------------------
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. --%>
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. */
This section provides tips on the technical details of adding notice files and source code headers.
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
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