Open Source Scaffold

Description

This repository contains a set of tools for creating and checking the licensing and standard practices in open source projects.

In detail, it includes:

• A CLI for scaffolding open source projects with the standard files, including workflows for license compliance and integrity checks, community guidelines, and more. Read the CLI section below for more information.
• A Github workflow automating the process of initializing a project with the standard files, by simply creating a new repository from this template and running the workflow. Read the Repository template section below for more information.
• A Github action enabling to check the scaffolding of open source projects, ensuring that some relevant files are not removed after creating the project. Read the Github action section below for more information.

Table of Contents

• Supported licenses
• Usage
  • Repository template
  • Node.js CLI
  • Github Action
• The scaffold
• Inputs
• Automatic Contributing License Agreement
• License Integrity check
• License Compliance check
• Next steps
• Configuring the repository

Supported licenses

This scaffold is able to create projects with the following licenses:

• Apache-2.0
• AGPL-3.0-only
• AGPL-3.0-or-later
• MPL-2.0
• MIT

Usage

Repository template

You can initialize a new open source project by creating a new repository from this template. Follow these steps:

1. Create a new repository: Click on the "Use this template" button in Github when creating a new repository, and select this template.
   • Important: Make sure to select the "Allow GitHub Actions to create and approve pull requests" option when creating the repository. This is required for the "Initialize repository" workflow to work properly. Go to "Settings" > "Actions" > "General" and select the option.
2. Run the "Initialize repository" workflow: After creating the repository, go to the "Actions" tab and run the "Initialize repository" workflow. Enter the required inputs and run the workflow. This will open a PR creating the initial files for your project, and removing the files from this template that are not needed in your project.
3. Rename the .github-draft folder: The PR creates a .github-draft branch that needs to be renamed to .github manually before merging it. Follow the instructions in the PR description to rename the folder and push the changes. (This is because creating workflow files from an action requires special permissions, and the process of granting them would be more complex than simply renaming the folder).
4. Sign the CLA: If you have not signed the CLA yet, you will need to do so. The PR will include a comment asking you to sign the CLA. Follow the instructions in the comment to sign the CLA.
5. Merge the PR

That's it! You can now start working on your project. Happy coding! 🚀

Important

Read the Next steps section for further info about the following steps to take after initializing the repository.

Node.js CLI

This repository also includes a Node.js CLI that can be used to create or update an open source project with the standard files.

To use it, run the following command:

npx @telefonica/opensource-scaffold create

The CLI will prompt you for the required inputs to create the project, and also will ask you for confirmation before overwriting existing files.

Tip

You can also use arguments to provide the required information without being prompted. Read the inputs section for more information, or run npx @telefonica/opensource-scaffold create --help.

Once the files are created, you are ready to commit and push the changes to your repository. Happy coding! 🚀

Important

Read the Next steps section for further info about the following steps to take after initializing the repository.

Github Action for checking the open source resources

This repository includes a Github Action that checks that the project contains the files that this scaffolding includes. It can be executed in PRs and pushes, ensuring that the project always remains compliant with the scaffolding.

Tip

This action is automatically added when using the scaffolding tools. So, usually you won't need to add it manually. But in case you need to do so, here you have an example:

name: Open Source checks
on:
  pull_request:
  push:
    branches:
      - main
jobs:
  check-opensource-scaffold:
    name: Check Open Source Scaffold
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        id: checkout
        uses: actions/checkout@v4

      - name: Run check
        uses: Telefonica/opensource-scaffold@v2

Tip

You can ignore some files when checking the open source resources by providing a list of glob patterns in the ignore input. For example, if your repository is a monorepo and you want to ignore the root CHANGELOG.md file, you can omit it by adding CHANGELOG.md to the ignore input. Read the inputs section for more information.

Inputs

The opensource-scaffold action supports the following inputs:

Name	Description	Type	Required	Default
log	The log level to use when running the action	String	No	info
ignore	A semicolon separated list of glob patterns to ignore files when checking the open source resources	String	No	-

Example:

- name: Check Open Source scaffold
  uses: Telefonica/opensource-scaffold@v2
  with:
    log: debug
    ignore: "CHANGELOG.md;**/ISSUE_TEMPLATE/**"

The scaffold

Once you initialize an open source project using this scaffold, it will include the following:

• Readme file:
  • Title, description, and table of contents of the project.
  • Link to the Contributing Guidelines
  • Link to the License file, and to the chosen license FAQ website.
• License file: The license file of the project, depending on the license selected for the project.
• Code of conduct: The code of conduct of the project. By default, it is the Contributor Covenant published at contributor-covenant.org.
• Contributing guidelines: The contributing guidelines of the project. It includes:
  • A link to the License file.
  • Instructions to fill the license headers that must be included in new files. Based on the instructions of the Software Package Data Exchange (SPDX) website
  • A link to the Code of Conduct.
  • A human-readable summary of the Contributor License Agreement, and links to the full CLA.
• Contributor license agreement: The Contributor License Agreement of the project.
  • It is based on the CLA of HashiCorp.
• Pull Request template: The pull request template of the project. It includes:
  • A template for the title and description of the pull request.
  • A checklist to ensure that the contributor has read and understood the CONTRIBUTING and CODE_OF_CONDUCT documents, and that the contributor accepts the storage of their Github user name for the purpose of future reference.
  • A reminder to sign the CLA through a comment in the PR.
• Issue templates: Templates for bug reports and feature requests. The user is enforced to use one of the provided templates. Creating new issues without using a template is not allowed. The templates are:
  • Bug report: A template for bug reports.
    • Includes a check to ensure that the contributor has read the Code of Conduct.
  • Feature request: A template for feature requests.
    • Includes a check to ensure that the contributor has read the Code of Conduct.
• A Github Workflow with open source checks: It is executed on every pull request and pushes to the main branch, and checks the following:
  • License Integrity check: Checks that all files in the project are rightly licensed. That is, it checks that all files have the expected license header according to the license chosen for the project and a given configuration.
  • License compliance check: Checks that the dependencies of the project are licensed under a license that is compatible with a given configuration. The configuration by default is the one defined in the Practical Guide to Open Source Software at Telefónica for the chosen project's license, but can be customized.
  • Open source resources check: Checks that the project still contains the files that have been created by this scaffold, ensuring that the project always remains compliant with the open source guidelines.
• A Github Workflow for automatic CLA signing: It automates the process of signing the CLA, by creating a comment in the pull request asking contributors who have not signed CLA to sign. It fails the pull request status check with a failure if the contributor has not signed the CLA.
• Changelog file: A changelog file to keep track of the changes in the project. It is based on the Keep a Changelog format.

Inputs

The CLI and the initialize workflow support the following inputs.

Tip

The CLI will prompt you for the required inputs when they are not provided as arguments.

Name	Description	Type	Required	Default	CLI	Workflow
license	The license to use for the project.	One of the SPDX supported license ids	Yes	-	--license	license
name	The name of the project.	String	Yes	-	--name	name
copyright	The copyright holder of the project.	String	Yes	-	--copyright	copyright
description	Project description	String	No	-	--description	description
email	The email of the project's community leader	String	No	-	--email	email
log	The log level to use when creating the scaffold	String	No	info	--log	Not supported. Always set to debug
repo	The repository URL of the project.	String	No	-	--repo	Not supported. Automatically set.
overwrite	Whether to overwrite existing files or not. When enabled, the CLI won't prompt for the files to overwrite	Boolean	No	-	--overwrite	Not supported. Automatically set to true
no-prompts	Whether to skip the prompts or not. When provided, the CLI won't prompt for any input	Boolean	No	-	--no-prompts	Not supported. Automatically set to true

Automatic Contributing License Agreement

The Contributor License Agreement (CLA) is a legal document that defines the terms under which a contributor is allowed to contribute to the project. It is a common practice in open source projects to ensure that the project owner has the necessary rights to distribute the contributions.

This scaffold includes a workflow that automates the process of signing the CLA. The workflow uses the lite version of the CLA Assistant tool, which is a free service that integrates with Github to manage the CLA process.

In this case, the signing of the CLA is done through a comment in the pull request. CLA workflow creates a comment on Pull Request asking contributors who have not signed CLA to sign and also fails the pull request status check with a failure. The contributors are requested to sign the CLA within the pull request by copy and pasting "I have read the CLA Document and I hereby sign the CLA" as a Pull Request comment like below. If the contributor has already signed the CLA, then the PR status will pass with success.

Warning

The data of the contributors signing the CLA is stored in a repository branch named chore/cla-signatures. It is created automatically when using the template and the Initialize Repository Workflow. If you have used the CLI, you should create the branch manually and push it to the repository.

License Integrity check

The scaffold includes a job in the "Open Source Checks" workflow that checks that all files in the project are rightly licensed.

This job uses the Telefonica/check-spdx-headers action to check the SPDX headers in the project. The configuration of the action is defined in the .github/check-spdx-headers.config.yml file. It is filled automatically with the inputs provided when creating the scaffold, but it can be also customized manually to fit better your project's needs.

License Compliance check

You should ensure that you are not incorporating third party software in the project under a license that is not compatible with the license selected for the overall project, or that is not compatible with your company's open source licensing guidelines.

For such purpose, this scaffold includes a job in the "Open Source Checks" workflow. This job uses the Telefonica/check-license-compliance github action. The configuration of the action is defined in the .github/check-license-compliance.config.yml file. It is filled automatically based on the license provided when creating the scaffold, but it can be also customized manually to fit better your project's needs.

Warning

The configuration of the allowed and forbidden licenses is created according to the Telefónica's open source guidelines, depending of the license you choose for your project. You should adapt it to your company's guidelines if they are different.

Tip

In repositories with GitHub Advanced Security enabled, you may use the Github's dependency-review-action instead of the Telefonica/check-license-compliance github action. In such case, modify the .github/workflows/open-source-checks.yml to change the action used in the check-license-compliance job.

Next steps

Once you have used the scaffolding tools to create the resources, you should follow these steps to finalize the setup of your project:

1. Ensure that the chore/cla-signatures branch exists: If you have used the CLI, you should create the chore/cla-signatures branch manually and push it to the repository. This branch is used to store the data of the contributors signing the CLA. Read the Automatic Contributing License Agreement section for more information.
2. Remember to configure the repository rules: Remember to configure the branch protection rules to require the different checks in PRs, including the CLA signing check and the open source resources checks. Read the Configuring the repository section for more information.
3. Configure the License integrity check: The scaffold creates a basic configuration for the license integrity check, but you should review it and adapt it to your project. Read the License Integrity check section for more information.
4. Configure the License compliance check: The repository creates a basic configuration for the license compliance check, but you should review it and adapt it to your project. Read the License Compliance check section for more information.
5. Finish the README file: The scaffold creates for you a README.md file with some basic information about the project and license, but you should fill it with the information about the project, how to install it, how to use it, etc. But remember to always keep the "Contributing" and "License" sections.
6. Finish the CONTRIBUTING file: You should do the same with the CONTRIBUTING.md file. You should fill the "Getting Started" section with the steps that a contributor should follow to start contributing to the project, and add as many sections as needed to explain the contribution process. But you should always keep the rest of sections about the licensing of new files, code of conduct and the CLA.

Warning

Before publishing the repository, you should ensure that your company's legal department has reviewed it.

Configuring the repository

As the scaffold creates Github workflows, you should configure the repository rules to require the different checks in PRs, etc.

You can use the rules json files mentioned in the next steps to create the rules easily by using the "Import a ruleset" button in the "Rulesets" tab of the repository settings.

You should configure at least next repository rules:

Protect the chore/cla-signatures branch

It should be protected to avoid accidental deletion. Note also that the CLA bot will commit to this branch, so it should be allowed to do so.

Tip

You have a template for this rule in the docs/repo-rule-cla-signatures.json file.

Protect the main branch

The main branch should be protected by requiring status checks to pass before merging, including the CLA signing check and the Open Source resources checks.

Tip

You have a template for this rule in the docs/repo-rule-main.json file.

Final notes

Tip

Remember also to provide a good description and topics for the repository in order to make it easier for others to find, use, and, hopefully, contribute to your project. 😉