This page contains information meant for LLNL Employees with instructions for how to mark their source code projects. It is not intended to serve as legal advice.
All LLNL software must contain the following files at the root of the source code repository:
All projects shall have a
README.md file at the root of the repository.
README.md must contain the LLNL release number
LLNL-CODE-XXXXXX). We recommend putting it at the bottom in a section
called “Release”. See
Additionally, we recommend that all projects have the following sections:
.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
for the basics. For inspiration, look at other projects’
files at software.llnl.gov, or take a look
simple README.md template.
At the root of every source code repository shall be the following text in a
This work was produced under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344. This work was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor Lawrence Livermore National Security, LLC, nor any of their employees makes any warranty, expressed or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or Lawrence Livermore National Security, LLC. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or Lawrence Livermore National Security, LLC, and shall not be used for advertising or product endorsement purposes.
Additional information about the Notice can be found in our LLNL/.github repo.
One of the following files must 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 repository was approved for release under a different open source license, the text of that license will be provided by the Innovation and Partnerships Office.
If your project has more than one license, then you must 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-MIT files. Because GitHub does not
automatically detect multiple licenses, we recommend also adding a
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
LICENSE-* files for an example of how to organize a project with
In addition to the required files above, you should read the following sections and determine whether they apply to your code.
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
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
contributed code is assumed to be under that license as well. The
Cardioid project makes this explicit
Cardioid is distributed under the terms of the MIT license. All new contributions must be made under this license.
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
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
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 like
Cardioid, you would add this at the
bottom of your README file:
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
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.
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
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
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.
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. See the U.S. Office of Scientific and Technical Information’s (OSTI’s) FAQ on DOIs for details about how DOIs work and why they are beneficial.
After your code receives an LLNL release number, the Information Management team will submit it to OSTI’s DOE CODE, which assigns DOIs to software and adds them to the DOE Code catalog. Contact OSTI with questions or concerns about this process.
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:
If you still have questions or need more information, contact the LLNL GitHub Admins.