Skip to content

Commit

Permalink
docs: Update CONTRIBUTING (#1666)
Browse files Browse the repository at this point in the history 
Signed-off-by: Ian Lewis <ianlewis@google.com>
  • Loading branch information
@ianlewis
ianlewis authored Feb 22, 2023
1 parent ac3dcf6 commit b7a34a6
Showing 1 changed file with 116 additions and 25 deletions.
141 changes: 116 additions & 25 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,26 @@ 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](https://github.com/slsa-framework/slsa-github-generator/issues) and file new ones, all feedback
is welcome!
base. Feel free to browse the [open issues] and file new ones, all feedback is
welcome!

<!-- markdown-toc --bullets="-" -i CONTRIBUTING.md -->

<!-- toc -->

- [Prerequisites](#prerequisites)
- [Create a GitHub account](#create-a-github-account)
- [Code of Conduct](#code-of-conduct)
- [Setting up your development environment](#setting-up-your-development-environment)
- [How can I help?](#how-can-i-help)
- [Development](#development)
- [Prerequisites](#prerequisites)
- [Create a GitHub account](#create-a-github-account)
- [Code of Conduct](#code-of-conduct)
- [Setting up your development environment](#setting-up-your-development-environment)
- [Making Changes](#making-changes)
- [Create a fork](#create-a-fork)
- [Create a test repo](#create-a-test-repo)
- [Development Basics](#development-basics)
- [Make your changes](#make-your-changes)
- [Run tests](#run-tests)
- [Submit a PR](#submit-a-pr)
- [Preferred Languages](#preferred-languages)
- [Testing](#testing)
- [Pre-submits and Unit Tests](#pre-submits-and-unit-tests)
Expand All @@ -30,20 +38,47 @@ is welcome!

<!-- tocstop -->

## Prerequisites
## 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](https://github.com/slsa-framework/slsa-github-generator/issues/new/choose).

## 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?](#how-can-i-help) for more info.

### Prerequisites

Before submitting code, you should first complete the following
prerequisites.

### Create a GitHub account
#### Create a GitHub account

Before you get started, you will need to [signup](http://github.com/signup) for a GitHub user account.
Before you get started, you will need to [signup](http://github.com/signup) for
a GitHub user account.

### Code of Conduct
#### Code of Conduct

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

### Setting up your development environment
#### 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.
Expand All @@ -70,18 +105,19 @@ install them on your development machine.
- [eslint](https://eslint.org/) (NOTE: eslint is installed automatically so you
don't need to install it)

## Development
### 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.

Local commands that can be used for development are defined in the
[Makefile](./Makefile). You can list the available targets by running `make`.
workflows. The workflows themselves must be tested in your own fork. You can
fork the slsa-github-generator repo via the [Fork
button](https://github.com/slsa-framework/slsa-github-generator/fork).

```
make
```
#### 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.
Expand All @@ -93,6 +129,55 @@ Some example test repos:
- [actions-test](https://github.com/ianlewis/actions-test/tree/main/.github/workflows)
- [slsa-on-github-test](https://github.com/laurentsimon/slsa-on-github-test/tree/main/.github/workflows)

#### Development Basics

Local commands that can be used for development are defined in the
[`Makefile`](./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.

```shell
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].

```shell
git commit -s
```

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

```shell
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](#testing) section for more info.

#### Submit a PR

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

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:
Expand Down Expand Up @@ -120,11 +205,11 @@ 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](.github/workflows)
they fail. These tests are located in the [`.github/workflows`](.github/workflows)
directory and begin with the prefix `pre-sumbit`.

Unit tests are run as pre-submit tests in the
[pre-submit.units.yml](.github/workflows/pre-submit.units.yml) file. You can run
[`pre-submit.units.yml`](.github/workflows/pre-submit.units.yml) file. You can run
unit tests locally using `make`. This requires that the Go runtime be installed.

```
Expand All @@ -141,10 +226,10 @@ make ts-test

This project has a number of End-to-End tests that are scheduled to run daily.
These tests are located in the
[example-package](https://github.com/slsa-framework/example-package/tree/main/.github/workflows)
[`example-package`](https://github.com/slsa-framework/example-package/tree/main/.github/workflows)
repository and include a number of testing workflows. Please read the e2e
testing
[README.md](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/README.md)
[`README.md`](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/README.md)
for more information about e2e tests.

### Linters
Expand All @@ -156,11 +241,11 @@ make lint
```

These linters will also run as GitHub checks for pull requests via
[pre-submit.lint.yml](.github/workflows/pre-submit.lint.yml) file.
[`pre-submit.lint.yml`](.github/workflows/pre-submit.lint.yml) file.

## Releasing

Please see [RELEASE.md](RELEASE.md).
Please see [`RELEASE.md`](RELEASE.md).

## Community

Expand All @@ -177,3 +262,9 @@ Communication about bugs, usage, and new feature development is also done on
[GitHub issues](https://github.com/slsa-framework/slsa-github-generator/issues).

[code of conduct]: https://github.com/slsa-framework/governance/blob/main/8._Code_of_Conduct.md
[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/)
[developer certificate of origin]: https://developercertificate.org/
[license]: ./LICENSE
[good first issue]: https://github.com/slsa-framework/slsa-github-generator/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
[help wanted]: https://github.com/slsa-framework/slsa-github-generator/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3Ahelp+wanted%22
[open issues]: https://github.com/slsa-framework/slsa-github-generator/issues

0 comments on commit b7a34a6

Please sign in to comment.