diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32519bac..2dd2ed80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,59 +2,63 @@ We welcome and encourage community contributions to go-tuf. -Please familiarize yourself with the Contribution Guidelines before contributing. +Please familiarize yourself with these Contribution Guidelines before contributing. There are many ways to help go-tuf besides contributing code: - - Fix bugs or file issues - - Provide feedback on the CLI experience or suggest feature enhancements. - - Improve documentation. + +- Fix bugs or file issues +- Provide feedback on the CLI experience or suggest feature enhancements. +- Improve documentation. + +Please follow the [code of conduct](CODE_OF_CONDUCT.md) when contributing to this project. ## Contributing Code Unless you are fixing a known bug, we strongly recommend discussing it with the community via a GitHub issue or Slack before getting started to ensure that your work is consistent with TUF's specification. -All contributions are made via pull request. All patches from all contributors get reviewed. See the Pull Request procedure. +All contributions are made via pull request. All patches from all contributors get reviewed. See the [Pull Request procedure](#pull-request-procedure). ## Pull Request Procedure -To make a pull request, you will need a GitHub account. See GitHub's documentation [forking](https://help.github.com/articles/fork-a-repo) and [pull requests](https://help.github.com/articles/using-pull-requests). +To make a pull request, you will need a GitHub account. See GitHub's documentation on [forking](https://help.github.com/articles/fork-a-repo) and [pull requests](https://help.github.com/articles/using-pull-requests). Pull requests should be targeted at the `master` branch. Before creating a pull request, go through this checklist: 1. Create a feature branch off of `master` so that changes do not get mixed up. 2. If your PR adds new code, it should include tests covering the new code. If your PR fixes a bug, it should include a regression test. -3. PRs that change user-facing behavior or CLI must have associated documentation. -4. All code comments and documentation are expected to have proper English grammar and punctuation. +3. PRs that change user-facing behavior or the command-line interface must have associated documentation. +4. All code comments and documentation are expected to have proper English grammar and punctuation. 5. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your local changes against the `master` branch. 6. Run the full project test suite with the `go test ./...` command and confirm that it passes. 7. Run `go fmt ./...`. When creating a PR, -1. Accept the Developer's Certificate of Origin on all commits (see above). -2. Your PR title should be descriptive, and generally start with a subsystem prefix (ex: `client: `). -3. Your PR commit message will be used as the commit message when your PR is merged. Update this field if your PR diverges during review. -4. Your PR description should have details on what the PR does. If it fixes an existing issue, include a line like "Fixes #XXXX". +1. Your PR title should be descriptive, and follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification (start with `fix:`, `feat:`, or similar). +2. Your PR commit message will be used as the commit message when your PR is merged. Update this field if your PR diverges during review. +3. Your PR description should have details on what the PR does. If it fixes an existing issue, include a line like "Fixes #XXXX". -When all of the tests are passing, maintainer(s) will be assigned to review and merge the PR. +When all of the tests are passing, maintainer(s) will be assigned to review and merge the PR. If you're having trouble getting tests to pass, feel free to tag in [MAINTAINERS](MAINTAINERS) for help, or ask in Slack (see [Communication](#communication) below). ## Communication We use the [#tuf](https://cloud-native.slack.com/archives/C8NMD3QJ3) and [#go-tuf](https://cloud-native.slack.com/archives/C02D577GX54) channel on [CNCF Slack](https://slack.cncf.io/). You are welcome to drop in and ask questions, discuss bugs, etc. -## Pull Request review policy +You might also be interested in the TUF community beyond go-tuf; good places to start include: -* Anyone is welcome to review any PR, whether they are a maintainer or not! -* Maintainers should aim to turn around reviews within one business day. -* See [MAINTAINERS](MAINTAINERS) for the current list of maintainers. -* It is expected that two maintainers from differing organizations approve the PR before a merge. This may be waived for PRs which only update docs or comments, or trivial changes to tests. +- [TUF mailing list](https://groups.google.com/g/theupdateframework) +- TUF community meetings (monthly; join the mailing list to receive invitations) -Maintainers should: -* Make sure that the PR title, commit message, and description are updated if the PR changes significantly during review. -* Ensure that the PR guidelines above are satisfied (tests are added, documentation is added, etc). +## Pull Request Review Policy + +* Anyone is welcome to review any PR, whether they are a maintainer or not! +* Maintainers should aim to turn around reviews within five business days; feel free to ping, or tag in specific maintainers if a PR is taking longer than that. +* See [MAINTAINERS](MAINTAINERS) for the current list of maintainers. +Maintainers should look in [MAINTAINERS.md](MAINTAINERS.md) for detailed quidelines. +TODO: code of conduct. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000..94bffbd2 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,48 @@ +# go-tuf maintainer guidelines + +These are expectations for the [MAINTAINERS](MAINTAINERS) of go-tuf; if you are not able to meet these requirements, please remove yourself from the list of maintainers. + +## Process + +Speedy communication makes contributors happy! + +- You should get notifications for all activity in this repository (using the "Watch" feature) and quickly triage each issue/PR as it comes in. + - (non-draft) PRs should have assigned reviewers. + - Important bugs and questions should have assignees. +- If you are assigned to review a PR, please try to *acknowledge* it within one business day (no need if you are OOO). +- Please review all PRs within five business days (of course, it's okay if you're OOO). +- Please use the review checklist below. +- We should make sure there's a reviewer for every PR with tests passing within + +Versioning: + +- go-tuf releases follow [SemVer](https://semver.org/) with the following modification: + - While go-tuf is pre-1.0, increment the minor version for any breaking changes (in SemVer, there are no guarantees about API stability). +- Releases should be tagged in this repository as usual in Go ([Publishing a module](https://go.dev/doc/modules/publishing)). + +Project management: + +- Try to keep issues up-to-date with status updates! + - Feel free to ping open issues to check on them. + - Use the "assignee" field to indicate when you are working on an issue. + - Use GitHub issue labels to describe the issue (exact labels are still changing, so just look through and add those that seem like a good fit). +- Before publishing a new release, there should be an associated [GitHub project](https://github.com/theupdateframework/go-tuf/projects?type=beta) to track issues. +- We will develop more process around project management after we get through the v0.4.0 release. + +## Review checklist + +Code review: + +- [ ] Tests pass (enforced by CI). +- [ ] There should be tests for any new functionality, and regression tests for any bugs. +- [ ] Any user-facing functionality changes/additions (public APIs, command-line interface) should be documented. +- [ ] Changes should be compliant with the [TUF specification](https://theupdateframework.github.io/specification/latest/). + +Pre-merge (check everything again before hitting the merge button!): + +- [ ] Approvals from two different organizations. + - This is *not* currently enforced by CI, though PRs must have at least 2 approvals. + - This may be waived for PRs which only update docs or comments, or trivial changes to tests. +- Make sure that the PR title, commit message, and description are updated if the PR changes significantly during review. + + diff --git a/README.md b/README.md index 5ea8554f..56f1ddb3 100644 --- a/README.md +++ b/README.md @@ -605,7 +605,7 @@ For the client package, see https://godoc.org/github.com/theupdateframework/go-t For the client CLI, see https://github.com/theupdateframework/go-tuf/tree/master/cmd/tuf-client. -## Development +## Contributing and Development For local development, `go-tuf` requires Go version 1.16 or 1.17. @@ -614,3 +614,5 @@ The [Python interoperability tests](client/python_interop/) require Python 3 package](https://github.com/theupdateframework/python-tuf) installed (`pip install tuf`). To update the data for these tests requires Docker and make (see test data [README.md](client/python_interop/testdata/README.md) for details). + +Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines before making your first contribution!