From 1684c680105f90a054f04e05b0f8ac540c4ef885 Mon Sep 17 00:00:00 2001 From: Zack Newman Date: Thu, 9 Jun 2022 13:11:34 -0400 Subject: [PATCH] docs: Update CONTRIBUTING.md, add MAINTAINERS.md (#309) * add contrbuting guidelines Signed-off-by: Asra Ali * Update CONTRIBUTING.md, add MAINTAINERS.md Follow-up from #190 (thanks @asraa!). I did not add a DCO requirement at this point, as that was controversial in #190. I filed #308 to track that. I tried to address all *other* feedback in #190. Fixes #212. Fixes #306. * Move docs into a "docs" folder. Fixes #303. * Whitespace fixes * Address PR comments - TODO for testing instructions - Remove obsolete TODO * Full URL in testing * Fix @joshuagl suggestions Co-authored-by: Asra Ali --- CONTRIBUTING.md | 1 - README.md | 4 ++- docs/CODE_OF_CONDUCT.md | 4 +++ docs/CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++ MAINTAINERS => docs/MAINTAINERS | 0 docs/MAINTAINERS.md | 48 ++++++++++++++++++++++++++ docs/TESTING.md | 3 ++ 7 files changed, 119 insertions(+), 2 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 docs/CODE_OF_CONDUCT.md create mode 100644 docs/CONTRIBUTING.md rename MAINTAINERS => docs/MAINTAINERS (100%) create mode 100644 docs/MAINTAINERS.md create mode 100644 docs/TESTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 71b39ce2..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -See the [Flynn contributing guide](https://flynn.io/docs/contributing). 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! diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..e9fdc17c --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,4 @@ +## The Update Framework Community Code of Conduct + +The Update Framework follows the [CNCF Code of +Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..be87d0ad --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing Guide + +We welcome and encourage community contributions to go-tuf. + +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. + +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 (see [Communication](#communication) below for details) 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](#pull-request-procedure). + + +## Pull Request Procedure + +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 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 (see [TESTING.md](TESTING.md) for details). +7. Run `go fmt ./...`. + +When creating a PR: + +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. 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. + +You might also be interested in the TUF community beyond go-tuf; good places to start include: + +- [TUF mailing list](https://groups.google.com/g/theupdateframework) +- TUF community meetings (monthly; join the mailing list or watch the Slack channel to see invitations) + + +## 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. diff --git a/MAINTAINERS b/docs/MAINTAINERS similarity index 100% rename from MAINTAINERS rename to docs/MAINTAINERS diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md new file mode 100644 index 00000000..9968fd39 --- /dev/null +++ b/docs/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 an assigned reviewer for every PR which has passing tests. + +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/docs/TESTING.md b/docs/TESTING.md new file mode 100644 index 00000000..715201b0 --- /dev/null +++ b/docs/TESTING.md @@ -0,0 +1,3 @@ +# Testing + +TODO([#301](https://github.com/theupdateframework/go-tuf/issues/301))