Fork me on GitHub

Software Licensing

This page contains information meant for projects with instructions for how to mark their source code projects. It is not intended to serve as legal advice.

Best practices

All software should contain the following files at the root of the source code repository:

1. README file

All projects should have a README.md file at the root of the repository.

Additionally, we recommend that all projects have the following sections:

The .md suffix stands for “markdown”. Markdown is a plain text format. It’s easy to read and write, but it also allows you to add simple formatting and links so that your README.md will render nicely on GitHub. Take a look at GitHub’s markdown guide for the basics. For inspiration, look at other projects’ README.md files in our catalog, or take a look at this simple README.md template.

2. Open Source LICENSE file

One of the following files should be included at the top level of your repository with the file name LICENSE. The only content which may be changed in the file is the copyright year.

If your project has more than one license, then you should include all of the relevant licenses in your repository. We recommend that you name them with descriptive suffixes. For example, if your project is dual licensed under Apache-2.0 and MIT, you should have top-level LICENSE-APACHE and LICENSE-MIT files. Because GitHub does not automatically detect multiple licenses, we recommend also adding a top-level COPYRIGHT file with a summary of license details. GitHub’s “view license” link will then point to this file. You can look at Spack and its README.md, COPYRIGHT, and LICENSE-* files for an example of how to organize a project with two licenses.

Other Considerations

In addition to the required files above, you should read the following sections and determine whether they apply to your code.

Contribution Policies

If you host your code publicly, you may receive contributions from outside the lab. You should consider documenting your contribution policies in your README.md or in a CONTRIBUTING.md file.

It is good practice to make the following details explicit:

With most open source projects, it is assumed that contributions are made under the same license under which the project is distributed. For example, if you distribute your project under the MIT license, contributed code is assumed to be under that license as well.

If you want to provide instructions to your users that they should follow when submitting code to your project, you can put these types of instructions in a CONTRIBUTING.md file. This file typically deals more with workflow than with copyright or other IP concerns. A link to this file is shown to users when they submit pull requests.

SPDX

SPDX is an emerging standard for concisely labeling source code with license information. While it is not a requirement, we encourage you to use SPDX identifiers in your code, as they significantly reduce the amount of license boilerplate included in each source file.

SPDX provides a standard list of license identifiers that can be used to label code. To use SPDX identifiers in your project, you should find your license’s short identifier in the list, and add a special SPDX-License-Identifier line to your README.md. For example, if your code is licensed under the MIT license, you would add this at the bottom of your README file:

SPDX-License-Identifier: MIT

Additionally, you can use SPDX to label your source files. While not all open source licenses require you to add license information to every source file, for projects that do require a copy in every file, the SPDX short headers are sufficient. For example, source files in Spack start with the following comment:

# Copyright 2013-2018 Lawrence Livermore National Security, LLC and other
# Spack Project Developers. See the top-level COPYRIGHT file for details.
#
# SPDX-License-Identifier: (Apache-2.0 OR MIT)

There are two interesting parts here. First, the copyright section prominently mentions LLNS. It also mentions other Spack developers, who hold the copyright on the parts of the code they contributed. The SPDX line allows us to avoid pasting much longer license headers into each file. All together, this makes for a much shorter and more concise header.

The Spack example mentions a COPYRIGHT file because Spack is dual-licensed (see above). If you just have a single license, you can simply refer to the LICENSE file in your header.

For more information on using SPDX in your code, see the SPDX website.

Developer Certificate of Origin

As mentioned above, the default assumption for open source projects is “inbound license = outbound license”, i.e., contributors provide their code under the same license under which the code is distributed. If this is not enough assurance for your project, you may elect to use the Developer Certificate of Origin (DCO) with your project.

In this model, you can require contributors to use Git’s sign-off feature to acknowledge the DCO. This is NOT a license nor a CLA, but instead is a positive assertion by the contributor that they are authorized to make the contribution they are making. You should document your project’s requirement of DCO sign-off in your README.md or your CONTRIBUTING.md file.

You are not required to use the DCO, and it may add overhead to your process that deters potential contributors. Unless you feel that you need this level of assurance for your project, we recommend that you simply rely on the default inbound = outbound assumption.

Digital Object Identifier (DOI)

A digital object identifier (DOI) is a unique persistent identifier that references a digital object and provides long-term access. Just as journal articles carry DOIs, so too can open source software repositories.

The U.S. Office of Scientific and Technical Information (OSTI) assigns DOIs to software after your code has been submitted to DOE CODE. See OSTI’s FAQ on DOIs for details about how DOIs work and why they are beneficial.

OSTI is evaluating a notification workflow that would let a developer know when a DOI has been assigned. Until then, you can find your repo’s DOI and add it to the repo by following these steps:

  1. Type in the name of your repo at DOE CODE, then select it.
  2. Look in the RESOURCE section for the DOI number.
  3. In the SAVE/SHARE section, click Export Metadata and download the YAML file.
  4. Include that file in your repo in one of two ways: