Skip to content

Latest commit

 

History

History
366 lines (264 loc) · 13.2 KB

CONTRIBUTING.md

File metadata and controls

366 lines (264 loc) · 13.2 KB
Raw

Contributor Guide

This guide will help you understand the overall organization of the slsa-github-generator project, and direct you to the best places to get started contributing. You'll be able to pick up issues, write code to fix them, and get your work reviewed and merged.

This document is the single source of truth for how to contribute to the code base. Feel free to browse the open issues and file new ones, all feedback is welcome!

How can I help?

There are many areas in the project that need help. These are managed in GitHub issues. Please let us know if you are willing to work on the issue and how you can contribute.

  • For new developers and contributors, please see issues labeled good first issue. These issues should require minimal background knowledge to contribute.
  • For slightly more involved changes that may require some background knowledge, please see issues labeled help wanted
  • For experienced developers, any of our open issues is open to contribution.

If you don't find an existing issue for your contribution feel free to create a new one.

Development

This section covers what you need to set up a development environment, how to make changes, and how to submit them.

Before you decide to make a change, please take some time to identify an existing issue where you would like to contribute, or create a new issue. See How can I help? for more info.

Prerequisites

Before starting development, you should first complete the following prerequisites.

Create a GitHub account

Before you get started, you will need to signup for a GitHub user account.

Code of Conduct

Please make sure to read and observe the Code of Conduct.

Setting up your development environment

It is not required to set up a developer environment in order to contribute to slsa-github-generator but it may be required for code changes.

slsa-github-generator uses primarily Go and TypeScript programming languages. However much of the logic of the project is implemented in GitHub Actions workflows that are written in YAML and make heavy use of Bash scripts.

This project also uses several formatters and linters in order to maintain code quality. If you wish to run these tools locally, follow the instructions for each of these to install them on your development machine.

The following tools are used but are vendored or installed automatically you don't need to install them.

  • autogen: For maintaining license headers.
  • prettier: For formatting Markdown, YAML, and TypeScript code.
  • markdown-toc: For updating Table of Contents in markdown.
  • eslint: For linting TypeScript code

Conventions

This section contains info on general software development conventions used by this project.

Code style and formatting

Code, scripts, and documentation should be formatted using a formatting tool.

  1. Go code should be is formatted using gofumpt.
  2. TypeScript code should be formatted using prettier.
  3. YAML should be formatted using prettier.
  4. Markdown should be formatted using prettier.
  5. Shell scripts should be formatted using shfmt.
  6. Markdown files may have a table of contents which should be synced using markdown-toc.
  7. All code files should include a copyright notice and license header.

You can format code by running make format. See Prerequisites for more info on the required tools.

Semantic Versioning

slsa-github-generator uses [Semantic Versioning] for release versions.

This means that when creating a new release version, in general, given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality in a backward compatible manner
  3. PATCH version when you make backward compatible bug fixes

Conventional Commits

PR titles should be in Conventional Commits format.

The following prefixes are supported:

  1. fix: patches a bug
  2. feat: introduces a new feature
  3. docs: a change in the documentation.
  4. chore: a change that performs a task but doesn't change functionality, such as updating dependencies.
  5. refactor: a code change that improves code quality
  6. style: coding style or format changes
  7. build: changes that affect the build system
  8. ci: changes to CI/CD configuration files or scripts
  9. perf: change to improve performance
  10. revert: reverts a previous change
  11. test: adds missing tests or corrects existing tests

See pr-title-checker-config.json for the full configuration.

Making Changes

This section will cover how to make changes and test them.

Create a fork

Since this project includes reusable workflows for use on GitHub Actions local development is limited to building and testing the binaries used by the reusable workflows. The workflows themselves must be tested in your own fork. You can fork the slsa-github-generator repo via the Fork button.

Create a test repo

Most workflows are actually run when pushing to GitHub so in order to test that a code change is working you may want to set up a GitHub repository for testing. This repository should have some workflows that call the actions or reusable workflows you are testing.

Some example test repos:

Development Basics

Local commands that can be used for development are defined in the Makefile. You can list the available targets by running make.

make

Make your changes

When making changes in your fork, start by making a new branch.

git checkout -b my-feature-branch

Make your changes and then commit them to your branch. Make sure to sign-off on your commits. This establishes Developer Certificate of Origin which indicates that you are the author of the changes and are able to submit it under the project LICENSE.

git commit -s

You may periodically need to merge with the main branch. Be sure to sign-off on the merges as well.

git merge --signoff main

Run tests

Before you submit your change run the unit tests and linters to ensure your changes are ready to go. See the Testing section for more info.

Updating Github Actions Dependencies

Renovate-Bot PRs

renovate-bot will periodically send PRs to update the package.json and package-lock.json in the Github Actions of this repo. But, it will not also automatically recompile the packages into .js files.

We use a Workflow Update actions dist post-commit to help maintainers easily recompile the Github Actions against a PR.

Use the UI to invoke the workflow

update-actions-dist-post-commit.yml

or invoke with

gh workflow run update-actions-dist-post-commit.yml -F pr_number=<pull request number>

Submit a PR

Once your change is ready you can submit a PR via the website.

Make sure your change adheres to the Code style and formatting guidelines.

The title of your PR should include a Conventional Commits prefix label. For example, bug fixes should be prefixed with "fix:". PRs for new features should be prefixed with "feat:" etc.

Please also include as much information as your can about your change and any relevant issues in the PR description.

Preferred Languages

We prefer the use of the following programming languages:

  • Go - For builders/generators.
  • TypeScript - For GitHub actions.
  • Bash - For scripts in GitHub actions and workflows.

We do not have a strict rule that proscribes the use of a specific language. However, any PRs that introduce a new language should include justification for adding the new language as well as a plan for adding the necessary tooling and testing infrastructure.

We will generally reject PRs that introduce the use of memory-unsafe languages or use of existing languages in memory-unsafe ways (e.g. the Go unsafe package). See the Security Policy for more info.

Testing

A number of automated tests and linters are used to maintain stability and good code quality. New PRs that include new functionality should include automated tests for that functionality.

Pre-submits and Unit Tests

Pre-submits run on each Pull Request and will block it from being merged if they fail. These tests are located in the .github/workflows directory and begin with the prefix pre-sumbit.

Unit tests are run as pre-submit tests in the pre-submit.units.yml file. You can run unit tests locally using make. This requires that the Go runtime be installed.

make unit-test

Tests for GitHub Actions created with Typescript require Jest.

make ts-test

End-to-End (e2e) Tests

This project has a number of End-to-End tests that are scheduled to run daily. These tests are located in the example-package repository and include a number of testing workflows. Please read the e2e testing README.md for more information about e2e tests.

Linters

You can run all linters using make.

make lint

These linters will also run as GitHub checks for pull requests via pre-submit.lint.yml file.

Releasing

Please see RELEASE.md.

Community

This project is part of the SLSA Community working with the SLSA Tooling SIG.

Communication

The #slsa-tooling channel in the OpenSSF Slack is used for communication and sharing ideas.

Communication about bugs, usage, and new feature development is also done on GitHub issues.