Contribution Guidelines for hosted projects

This document captures the general guidelines for contributing to open-source projects hosted by Open Mainframe Project. These guidelines express the provisions in the Intellectual Property Policy within Open Mainframe Project charter.

Note that each hosted project may adopt its guidelines, which would supersede these provisions in the case of conflict.

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

All source code must clearly identify the open-source license used. The Open Mainframe Project charter dictates Apache 2 by default, except for Linux kernel code which must be GPLv2 unless a specific project charter’s intellectual property policy states otherwise. The Project will receive and make all documentation and other non-code assets available under the Creative Commons Attribution 4.0 International License (available at http://creativecommons.org/licenses/by/4.0/).

Requirements to ensure license compliance

  • 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 has standardized on including SPDX short-form license identifiers and a general copyright statement as shown below ( this example is for Apache 2.0 licensed code ):
/**
  Copyright Contributors to the [NAME OF PROJECT] Project.

  SPDX-License-Identifier: Apache-2.0
**/

The license may be omitted for property or configuration files that do not support comments. If comments are supported, the license header should be included.

Contributors may include a copyright statement specifying themselves or their employer (as applicable) as the copyright holder of their contributions, but the Open Mainframe Project does not require or recommend this.

Finally, please note that pre-existing third-party license notices and copyright notices should not be modified or removed by anyone other than the copyright holder. Any questions on including code under a different license than the project should be discussed with the project lead and Open Mainframe Project Governing Board.

Developer Certificate of Origin

Open Mainframe Project requires the Developer’s Certificate of Origin 1.1 (DCO), the same mechanism 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.

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

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

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

Additionally, it is possible to use shell scripting to apply signoff automatically. 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 Signed-off-by:</code> 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.

If you are using one of the recommended GitHub UI integrations for adding the signoff automatically, you should ensure that the name and email listed there match that which is in your GitHub profile.

Examples of the UI elements to match are below.

GitHub user profile (https://github.com/settings/profile)