From b2d546a38bac2e36d77a176b757112492c8db65e Mon Sep 17 00:00:00 2001 From: Asra Ali Date: Thu, 9 Dec 2021 14:35:14 -0600 Subject: [PATCH 1/7] add contrbuting guidelines Signed-off-by: Asra Ali --- CONTRIBUTING.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71b39ce2..32519bac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,60 @@ -See the [Flynn contributing guide](https://flynn.io/docs/contributing). +# Contributing Guide + +We welcome and encourage community contributions to go-tuf. + +Please familiarize yourself with the 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. + +## 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. + + +## 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). + +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. +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". + +When all of the tests are passing, maintainer(s) will be assigned to review and merge the PR. + + +## 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 + +* 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. + +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). + + + + From a2f92c4999256ad106b88d96cb7629621511e66e Mon Sep 17 00:00:00 2001 From: Zachary Newman Date: Wed, 8 Jun 2022 14:08:53 -0400 Subject: [PATCH 2/7] 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. --- CONTRIBUTING.md | 46 +++++++++++++++++++++++++--------------------- MAINTAINERS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +++- 3 files changed, 76 insertions(+), 22 deletions(-) create mode 100644 MAINTAINERS.md 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! From bf950ce630e3a53c3a7037132275ba827db7c5c5 Mon Sep 17 00:00:00 2001 From: Zachary Newman Date: Wed, 8 Jun 2022 14:45:41 -0400 Subject: [PATCH 3/7] Move docs into a "docs" folder. Fixes #303. --- docs/CODE_OF_CONDUCT.md | 4 ++++ CONTRIBUTING.md => docs/CONTRIBUTING.md | 0 MAINTAINERS => docs/MAINTAINERS | 0 MAINTAINERS.md => docs/MAINTAINERS.md | 0 4 files changed, 4 insertions(+) create mode 100644 docs/CODE_OF_CONDUCT.md rename CONTRIBUTING.md => docs/CONTRIBUTING.md (100%) rename MAINTAINERS => docs/MAINTAINERS (100%) rename MAINTAINERS.md => docs/MAINTAINERS.md (100%) 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/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md diff --git a/MAINTAINERS b/docs/MAINTAINERS similarity index 100% rename from MAINTAINERS rename to docs/MAINTAINERS diff --git a/MAINTAINERS.md b/docs/MAINTAINERS.md similarity index 100% rename from MAINTAINERS.md rename to docs/MAINTAINERS.md From 3b08a825da030358c74375ec78848d03236a8a15 Mon Sep 17 00:00:00 2001 From: Zachary Newman Date: Wed, 8 Jun 2022 15:02:28 -0400 Subject: [PATCH 4/7] Whitespace fixes --- docs/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2dd2ed80..7dd8d3da 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -21,7 +21,7 @@ All contributions are made via pull request. All patches from all contributors g ## 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). +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: @@ -33,7 +33,7 @@ Pull requests should be targeted at the `master` branch. Before creating a pull 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, +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. From c69e3d3f1e1ae3da0edf5bc214e1e9c49fb92baa Mon Sep 17 00:00:00 2001 From: Zachary Newman Date: Wed, 8 Jun 2022 15:38:06 -0400 Subject: [PATCH 5/7] Address PR comments - TODO for testing instructions - Remove obsolete TODO --- docs/CONTRIBUTING.md | 5 +---- docs/TESTING.md | 3 +++ 2 files changed, 4 insertions(+), 4 deletions(-) create mode 100644 docs/TESTING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7dd8d3da..553ed2e3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -30,7 +30,7 @@ Pull requests should be targeted at the `master` branch. Before creating a pull 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. +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: @@ -59,6 +59,3 @@ You might also be interested in the TUF community beyond go-tuf; good places to * 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/docs/TESTING.md b/docs/TESTING.md new file mode 100644 index 00000000..6e69a480 --- /dev/null +++ b/docs/TESTING.md @@ -0,0 +1,3 @@ +# Testing + +TODO(#301) From 21c807eafb569066482f96a96d6b799807650310 Mon Sep 17 00:00:00 2001 From: Zachary Newman Date: Wed, 8 Jun 2022 16:19:19 -0400 Subject: [PATCH 6/7] Full URL in testing --- docs/TESTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TESTING.md b/docs/TESTING.md index 6e69a480..715201b0 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -1,3 +1,3 @@ # Testing -TODO(#301) +TODO([#301](https://github.com/theupdateframework/go-tuf/issues/301)) From 0bfab6f2974afbbdd3b0585c043dfcd277e51f8c Mon Sep 17 00:00:00 2001 From: Zachary Newman Date: Wed, 8 Jun 2022 17:51:56 -0400 Subject: [PATCH 7/7] Fix @joshuagl suggestions --- docs/CONTRIBUTING.md | 6 +++--- docs/MAINTAINERS.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 553ed2e3..be87d0ad 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -6,7 +6,7 @@ Please familiarize yourself with these Contribution Guidelines before contributi There are many ways to help go-tuf besides contributing code: -- Fix bugs or file issues +- Fix bugs or file issues. - Provide feedback on the CLI experience or suggest feature enhancements. - Improve documentation. @@ -14,7 +14,7 @@ Please follow the [code of conduct](CODE_OF_CONDUCT.md) when contributing to thi ## 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. +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). @@ -49,7 +49,7 @@ We use the [#tuf](https://cloud-native.slack.com/archives/C8NMD3QJ3) and [#go-tu 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 to receive invitations) +- TUF community meetings (monthly; join the mailing list or watch the Slack channel to see invitations) ## Pull Request Review Policy diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index 94bffbd2..9968fd39 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -12,7 +12,7 @@ Speedy communication makes contributors happy! - 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 +- We should make sure there's an assigned reviewer for every PR which has passing tests. Versioning: