Contribution Guidelines for hosted projects

This document is intended to outline the recommended licensing and contribution standards for any project intended for being hosted by the Open Mainframe Project.

Within open source, there are multiple approaches to contribution and licensing, and Open Mainframe Project recognizes that there is no single strategy that fits all project communities and consumers. This document is not intended to endorse any particular license or contribution strategy but instead to provide guidance on best practices based on experiences with other projects (both Open Mainframe Project-hosted and others within the industry). Please consult your legal counsel for specific guidance for your situation.

Two-factor Authentication (2FA)

To enable more robust security for hosted projects, Open Mainframe Project TAC requires all hosted projects to require Two-factor authentication (2FA) for accessing code repositories. Instructions for GitHub are below…

License Specification

Generally open source projects at The Linux Foundation that have not previously selected a license leverage the Apache License, Version 2.0 for their codebase, a Community Data License Agreement (CDLA) license for any data sets, and the Creative Commons Attribution 4.0 International License for all documentation and non-code assets. These licenses are widely used and understood by developers and organizations alike, providing flexibility for downstream usage and patent protection for those contributing code. Each hosted project maintains their own Intellectual Property policy as part of thier Technical Charter which outlines the specific guidelines.

Code License Identification

Each repository must contain a license file. Include the plain-text version of the license as a LICENSE file in the top-level directory of the repository.

All source files need to include a header to clearly show the license. Open Mainframe Project recommends using SPDX short-form license identifiers in source code files, which vastly reduces errors in copy and pasting license text and enables the headers to be machine-readable. An example of the use of SPDX short-form license identifiers can be found here.

We have recommended that contributors to a new project establish a common format for copyright notices in their own code. This can help minimize compliance burdens that might otherwise require downstream distributors to reproduce many variations in years, entity names, and formats for notices. We recommend a common copyright notice in a form similar to the following, which does not refer to years or specific contributing entities:

Copyright Contributors to the __________ Project.

For clarity, we would not recommend removing a third party’s license or copyright notice in any circumstance. If a third-party dependency is added to a repository, its license and copyright notices should be preserved and should not be modified or removed.

Assumes Apache License, Version 2.0 and Foo project name.

# SPDX-License-Identifier: Apache-2.0
# Copyright Contributors to the Foo Project.

Contribution sign off

Ensuring a clean code pedigree and lineage is critical to the industry’s downstream adoption of open-source code.

Open Mainframe Project requires the use of the Developer’s Certificate of Origin 1.1 (DCO), which is the same mechanism that the Linux® Kernel and many other communities use to manage code contributions. The DCO is considered one of the simplest tools for sign-offs from contributors as the representations are meant to be easy to read and indicate signoff is done as a part of the commit message. The DCO is a representation by someone stating they have the right to contribute the code they have proposed for acceptance into a project. That representation is important for legal purposes and was the community-developed outcome after a $1 billion lawsuit by SCO against IBM. The representation is designed to prevent issues but also keep the burden on contributors low. It has proven very adaptable to other projects, is built into git itself (and now also GitHub), and is in use by thousands of projects to avoid more burdensome requirements to contribute (such as a CLA).

Here is an example Signed-off-by line, which indicates that the submitter accepts the DCO:

Signed-off-by: John Doe <john.doe@example.com>

You can include this automatically when you commit a change to your local git repository using git commit -s.

DCO and Real Names

The DCO requires the use of a real name that can be used to identify someone in case there is an issue about a contribution they made.

A real name does not require a legal name, nor a birth name, nor any name that appears on an official ID (e.g. a passport). Your real name is the name you convey to people in the community for them to use to identify you as you. The key concern is that your identification is sufficient enough to contact you if an issue were to arise in the future about your contribution.

Your real name should not be an anonymous id or false name that misrepresents who you are.

Additional context can be found here.

Make doing DCO signoffs easier

By default, all GitHub repositories have both the GitHub DCO App installed and commit signoffs enabled. This ensures anyone contributing via the GitHub web interface will automatically signoff commits.

For developers working from thier local machines, there are a few options available to automatically signoff commits.

  • DCO command line tool, which lets you do a single signoff for an entire repo.
  • Shell scripting to automatically apply signing. Here is an example for bash, to be put into a .bashrc file:
git() {
    if [[ $1 == "commit" ]]; then
        shift
        echo "Executing git commit -s $@"
        command git commit -s "$@"
    else
        command git "$@"
    fi
}

Signoff for commits where the DCO signoff was missed

When bringing in a code repository for the first time or commits done before the DCO checks are enabled, there would be a series of commits that don’t include the sign-off statement. You can retroactively signoff commits you’ve made by making a commit with your DCO signoff that contains a new text file (the suggested name is past_commits.txt ) with the following contents:

The following commits were made pursuant to the Developer Certificate of Origin, even though a Signed-off-by: was not included in the commit message.

<COMMIT HASH> <COMMIT MSG>
...

Each user who has made the past commits should have their own Signed-off-by: line in the commit message.

This process can be automated using the DCO Org Check script.

Handling DCO errors using GitHub website commits.

The Probot: DCO app requires that the email address and name specified in the DCO Signoff match that of the current information from the user making the commit. Generally, this is handled automatically when using a local git client, but when making contributions from the GitHub website directly, this needs to be aligned manually.