From ee358af4e4310d7447a4d89d4a0d5878dc77a8df Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sun, 23 Apr 2023 20:27:22 +0800 Subject: [PATCH 01/19] doc: update contributing guide Signed-off-by: Yi Zha --- CONTRIBUTING.md | 128 +++++++++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 61 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64d2326..4f52465 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,95 +1,101 @@ -# Contributing to notary +# Contributing Guidelines -## Before reporting an issue... +Welcome to the notary community. The Notary project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted. -### If your problem is with... +## Overview of Notary project - - automated builds - - your account on the [Docker Hub](https://hub.docker.com/) - - any other [Docker Hub](https://hub.docker.com/) issue +The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary project umbrella: -Then please do not report your issue here - you should instead report it to [https://support.docker.com](https://support.docker.com) +- [notation](https://github.com/notaryproject/notation), a CLI project to add signatures as standard items in the registry ecosystem, and to build a set of simple tooling for signing and verifying these signatures. +- [notation-go](https://github.com/notaryproject/notation-go), a library project to support sign and verify artifacts and store signatures in the registry. +- [notation-core-go](https://github.com/notaryproject/notation-core-go), a library project to support Notary signature envelope and format specific implementation. +- [notaryproject](https://github.com/notaryproject/notatryproject), a project for Notary project requirements and specifications. +- [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev), a project for Notary project website. +- [.github](https://github.com/notaryproject/.github), a project for notary project governance documents. +- [meeting-notes](https://github.com/notaryproject/meeting-notes), a project for archived meeting notes. +- [tuf](https://github.com/notaryproject/tuf), a project to implement the full TUF specification in a registry native way. +- [notary](https://github.com/notaryproject/notatry), the original project, which is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry. -### If you... +## Support Channels - - need help setting up notary - - can't figure out something - - are not sure what's going on or what your problem is +Whether you are a user or contributor, official support channels include: -Then please do not open an issue here yet - you should first try one of the following support forums: +- Issues for each repository. You can use [Notation issue](https://github.com/notaryproject/notation/issues) if you are not sure about which repository to be involved. +- Slack: [#notary-project](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/) +- [Public community meetings](https://notaryproject.dev/community/#cncf-public-events-calendar) + - Catch up with [past meetings on YouTube](https://www.youtube.com/@CNCFNotary) - - irc: #docker-trust on freenode +## Reporting Security Issues -## Reporting an issue properly +If you are reporting a security vulnerability, Please DO NOT file a public issue. -By following these simple rules you will get better and faster feedback on your issue. +Please refer to [Security Guide here](SECURITY.md) on how to report security vulnerabilities. - - search the bugtracker for an already reported issue +## Reporting Other Issues -### If you found an issue that describes your problem: +It is a great way to contribute to notary project by reporting issues. Please open an issue on Github and follow the template to fill in required information. - - please read other user comments first, and confirm this is the same issue: a given error condition might be indicative of different problems - you may also find a workaround in the comments - - please refrain from adding "same thing here" or "+1" comments - - you don't need to comment on an issue to get notified of updates: just hit the "subscribe" button - - comment if you have some new, technical and relevant information to add to the case +Before opening any issue, please look up the existing issues to avoid submitting a duplication. If you found an issue that describes your problem: -### If you have not found an existing issue that describes your problem: +- please read other user comments first, and confirm this is the same issue: a given error condition might be indicative of different problems - you may also find a workaround in the comments +- please refrain from adding "same thing here" or "+1" comments +- you don't need to comment on an issue to get notified of updates: just hit the "subscribe" button +- comment if you have some new, technical and relevant information to add to the case - 1. create a new issue, with a succinct title that describes your issue: - - bad title: "It doesn't work with my docker" - - good title: "Publish fail: 400 error with E_INVALID_DIGEST" - 2. copy the output of: - - `notary version` or `docker version` - 3. Run `notary` or `docker` with the `-D` option for debug output, and please include a copy of the command and the output. - 4. If relevant, copy your `notaryserver` and `notarysigner` logs that show the error (this is likely the output from running `docker-compose up`) +## Contributing Workflow -## Contributing a patch for a known bug, or a small correction +PR are always welcome, even if they only contain small fixes like typos or a few lines of code. If there will be a significant effort, please document it as an issue and get a discussion going before starting to work on it. -You should follow the basic GitHub workflow: +Please submit a PR broken down into small changes bit by bit. A PR consisting of a lot of features and code changes may be hard to review. It is recommended to submit PRs in an incremental fashion. - 1. fork - 2. commit a change - 3. make sure the tests pass - 4. PR +Note: If you split your pull request to small changes, please make sure any of the changes goes to main will not break anything. Otherwise, it can not be merged until this feature complete. -Additionally, you must [sign your commits](https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work). It's very simple: +- Fork and clone - - configure your name with git: `git config user.name "Real Name" && git config user.email mail@example.com` - - sign your commits using `-s`: `git commit -s -m "My commit"` + Fork the repository and clone the code to your local workspace. -Some simple rules to ensure quick merge: +- Branch - - clearly point to the issue(s) you want to fix in your PR comment (e.g., `closes #12345`) - - prefer multiple (smaller) PRs addressing individual issues over a big one trying to address multiple issues at once - - if you need to amend your PR following comments, please squash instead of adding more commits - - if fixing a bug or adding a feature, please add or update the relevant `CHANGELOG.md` entry with your pull request number - and a description of the change + Changes should be made on your own fork in a new branch checked out from the `main` branch. -## Contributing new features +- Develop, Build and Test + + Write code on the new branch in your fork. Unit test cases should be added to cover the new code. For PR in [notation](https://github.com/notaryproject/notation), end-to-end (e2e) test cases should be added, see [e2e quick start](https://github.com/notaryproject/notation/blob/main/test/e2e/README.md) + +- Keep sync with upstream + + Once your branch gets out of sync with the `main` branch, please fetch and rebase from `main` branch. + +- Commit + + As Notary project repositories has integrated the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) check tool, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. -You are heavily encouraged to first discuss what you want to do. You can do so on the irc channel, or by opening an issue that clearly describes the use case you want to fulfill, or the problem you are trying to solve. + Notary project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. -If this is a major new feature, you should then submit a proposal that describes your technical solution and reasoning. -If you did discuss it first, this will likely be greenlighted very fast. It's advisable to address all feedback on this proposal before starting actual work +- Push and Create PR + + When ready for review, push your branch to your fork repository, and [create a new pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui). Description of a pull request should refer to all the issues that it addresses. Remember to put a reference to issues (such as Closes #XXX and Fixes #XXX) in commits so that the issues can be closed when the PR is merged. + + Once your pull request has been opened it will be assigned to reviewers automatically based on CODEOWNERS. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style. + + Commit changes made in response to review comments to the same branch on your fork. + +## Contributing new features -Then you should submit your implementation, clearly linking to the issue (and possible proposal). +You are heavily encouraged to first discuss what you want to do. You can do so on the slack channel, or by opening an issue that clearly describes the use case you want to fulfill, or the problem you are trying to solve. If this is a new feature, you should then submit a proposal that describes your technical solution and reasoning. It's advisable to address all feedback on this proposal before starting actual work. For new feature requiring changes on Notation CLI flags or commands, the proposal should include the changes on the CLI specification, see [Notation CLI index file](https://github.com/notaryproject/notation/blob/main/specs/notation-cli.md). -Your PR will be reviewed by the community, then ultimately by the project maintainers, before being merged. +After issue and solution proposal are approved by maintainers, you should submit PR based on [Contributing Workflow](#contributing-workflow) -It's mandatory to: +## Documenting - - interact respectfully with other community members and maintainers - more generally, you are expected to abide by the [Docker community rules](https://github.com/docker/docker/blob/master/CONTRIBUTING.md#docker-community-guidelines) - - address maintainers' comments and modify your submission accordingly - - write tests for any new code +Update the documentation if you are creating or changing features. Good documentation is as important as the code itself. -Complying to these simple rules will greatly accelerate the review process, and will ensure you have a pleasant experience in contributing code to the Registry. +The main location for the documentation is the [website repository](https://github.com/notaryproject/notaryproject.dev). -## Review and Development notes +Documents are written with Markdown. See [Writing on GitHub](https://docs.github.com/en/get-started/writing-on-github) for more details. -- All merges require LGTMs from any 2 maintainers. -- We use the git flow model (as best we can) using the `releases` branch as the stable branch, and the `master` branch as the development branch. When we get near a potential release, a release branch (`release/`) will be created from `master`. Any PRs that should go into the release should be made against that branch. Hotfixes for a minor release will be added to the branch `hotfix/`. +Documentation PRs will follow the same workflow as other PRs. -## Vendoring new dependency versions +## Credits -We use [VNDR](https://github.com/LK4D4/vndr); please update `vendor.conf` with the new dependency or the new version, and run -`vndr `. \ No newline at end of file +We would like to give credit to the [Helm Community](https://github.com/helm/community) and the [Harbor Community](https://github.com/goharbor/harbor/) for using their contributing guide as references. From d54cf5d081e15a9bcbc1f36102ad6b4c5d3a073f Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 25 Apr 2023 19:11:43 +0800 Subject: [PATCH 02/19] doc: update labels and issues LCM Signed-off-by: Yi Zha --- CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f52465..00416f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,6 +42,29 @@ Before opening any issue, please look up the existing issues to avoid submitting - you don't need to comment on an issue to get notified of updates: just hit the "subscribe" button - comment if you have some new, technical and relevant information to add to the case +Issues will be marked with different labels for different purpose, see [Labels](#labels) for details. + +### Issue Lifecycle + +The issue lifecycle is mainly driven by the maintainers. + +1. Issue creation: + - After an issue is created, it will be labelled `bug` or `enhancement`, and `triage`. +2. Triage: The maintainers will triage the issues. The results of triage could be one of the following: + - Remove label `triage`, and add the issues to the correct milestone + - Keep label `triage` to indicate that further triage is required. + - Remove label `triage`, and labelled `wont fix` to indicate this issue is out of the scope of Notary or other reasons. +3. Development: + - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation + - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it +4. Issue closure + - Close the issue once PRs are merged + - Close the issue once the author accepts the `wont fix` decision. + +## Support requests or questions + +Please use slack channel for support requests or questions. Issues could be created accordingly if it is a bug or enhancement. + ## Contributing Workflow PR are always welcome, even if they only contain small fixes like typos or a few lines of code. If there will be a significant effort, please document it as an issue and get a discussion going before starting to work on it. @@ -96,6 +119,31 @@ Documents are written with Markdown. See [Writing on GitHub](https://docs.github Documentation PRs will follow the same workflow as other PRs. +## Labels + +The following tables define all label types used for Notary project. It is split up by category. + +### Common + +| Label | Description | +| --------------- | --------------------------------------------------------------------------- | +| `bug` | Marks an issue as a bug or a PR as a bugfix | +| `documentation` | Indicates the issue or PR is a documentation change | +| `duplicate` | Marks an issue or PR already exists | +| `enhancement` | Marks the issue as a feature request or a PR as a feature implementation | +| `keep open` | Denotes that the issue or PR should be kept open past 30 days of inactivity | +| `testing` | Marks an issue or PR is related to testing | +| `triage` | Indicates the issue or PR needs triage | +| `UX` | Marks an issue or PR is related to user experience | + +### Issue Specific + +| Label | Description | +| ------------------ | ------------------------------------------------------------------------ | +| `help wanted` | Marks an issue needs help from the community to solve | +| `good first issue` | Marks an issue as a good starter issue for someone new to Notary project | +| `wont fix` | Marks an issue as discussed and will not be implemented | + ## Credits We would like to give credit to the [Helm Community](https://github.com/helm/community) and the [Harbor Community](https://github.com/goharbor/harbor/) for using their contributing guide as references. From aa74beb98188da2548a8903089c3745305d8d393 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 27 Apr 2023 14:15:36 +0800 Subject: [PATCH 03/19] doc: update per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 58 +++++++++++++++++++++++++++---------------------- 1 file changed, 32 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00416f1..f2c1431 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,30 +6,32 @@ Welcome to the notary community. The Notary project accepts contributions via Gi The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary project umbrella: -- [notation](https://github.com/notaryproject/notation), a CLI project to add signatures as standard items in the registry ecosystem, and to build a set of simple tooling for signing and verifying these signatures. -- [notation-go](https://github.com/notaryproject/notation-go), a library project to support sign and verify artifacts and store signatures in the registry. -- [notation-core-go](https://github.com/notaryproject/notation-core-go), a library project to support Notary signature envelope and format specific implementation. -- [notaryproject](https://github.com/notaryproject/notatryproject), a project for Notary project requirements and specifications. -- [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev), a project for Notary project website. -- [.github](https://github.com/notaryproject/.github), a project for notary project governance documents. -- [meeting-notes](https://github.com/notaryproject/meeting-notes), a project for archived meeting notes. -- [tuf](https://github.com/notaryproject/tuf), a project to implement the full TUF specification in a registry native way. -- [notary](https://github.com/notaryproject/notatry), the original project, which is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry. +| Repository | Description | +| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [notation](https://github.com/notaryproject/notation) | A CLI project to add signatures as standard items in the registry ecosystem, and to build a set of simple tooling for signing and verifying these signatures | +| [notation-go](https://github.com/notaryproject/notation-go) | A library project to support sign and verify artifacts and store signatures in the registry | +| [notation-core-go](https://github.com/notaryproject/notation-core-go) | A library project to support Notary signature envelope and format specific implementation | +| [notaryproject](https://github.com/notaryproject/notatryproject) | A project for Notary project requirements and specifications | +| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | A project for Notary project website | +| [.github](https://github.com/notaryproject/.github) | A project for notary project governance documents | +| [meeting-notes](https://github.com/notaryproject/meeting-notes) | A project for archived meeting notes | +| [tuf](https://github.com/notaryproject/tuf) | A project to implement the full TUF specification in a registry native way | +| [notary](https://github.com/notaryproject/notatry) | The original project, which is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry | ## Support Channels Whether you are a user or contributor, official support channels include: - Issues for each repository. You can use [Notation issue](https://github.com/notaryproject/notation/issues) if you are not sure about which repository to be involved. -- Slack: [#notary-project](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/) +- Slack: [#notary-project](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/). Join [slack](https://slack.cncf.io/) if it is your first time using Slack. - [Public community meetings](https://notaryproject.dev/community/#cncf-public-events-calendar) - Catch up with [past meetings on YouTube](https://www.youtube.com/@CNCFNotary) ## Reporting Security Issues -If you are reporting a security vulnerability, Please DO NOT file a public issue. +> **Warning** If you are reporting a security vulnerability, Please DO NOT file a public issue. -Please refer to [Security Guide here](SECURITY.md) on how to report security vulnerabilities. +Please refer to [Security Guide](SECURITY.md) on how to report security vulnerabilities. ## Reporting Other Issues @@ -37,10 +39,9 @@ It is a great way to contribute to notary project by reporting issues. Please op Before opening any issue, please look up the existing issues to avoid submitting a duplication. If you found an issue that describes your problem: -- please read other user comments first, and confirm this is the same issue: a given error condition might be indicative of different problems - you may also find a workaround in the comments -- please refrain from adding "same thing here" or "+1" comments -- you don't need to comment on an issue to get notified of updates: just hit the "subscribe" button -- comment if you have some new, technical and relevant information to add to the case +- Please read other user comments first to confirm if they have experienced the same issue. Keep in mind that a given error condition might be indicative of different problems. You may also find a workaround in the comments +- To receive updates on an issue, simply click the 'subscribe' button +- Please only comment if you have new, technical, and relevant information to add to the case. Issues will be marked with different labels for different purpose, see [Labels](#labels) for details. @@ -52,14 +53,18 @@ The issue lifecycle is mainly driven by the maintainers. - After an issue is created, it will be labelled `bug` or `enhancement`, and `triage`. 2. Triage: The maintainers will triage the issues. The results of triage could be one of the following: - Remove label `triage`, and add the issues to the correct milestone - - Keep label `triage` to indicate that further triage is required. + - Keep label `triage` to indicate that further triage is required - Remove label `triage`, and labelled `wont fix` to indicate this issue is out of the scope of Notary or other reasons. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it 4. Issue closure - Close the issue once PRs are merged - - Close the issue once the author accepts the `wont fix` decision. + - Close the issue once the author accepts the `wont fix` decision + +### Stale issues or PRs + +A stale issue or pull request (PR) is one that has not had any activity or updates for 60 days. When an issue or PR becomes stale, it is labelled as `stale`. Normally maintainers will comment on stale issue or PR to prompt participants to take action. Then, if no additional activity occurs after 14 days, this issue or PR will be closed. If an update/comment occur on stale issues or pull requests, the stale label will be removed and the timer will restart. ## Support requests or questions @@ -71,33 +76,33 @@ PR are always welcome, even if they only contain small fixes like typos or a few Please submit a PR broken down into small changes bit by bit. A PR consisting of a lot of features and code changes may be hard to review. It is recommended to submit PRs in an incremental fashion. -Note: If you split your pull request to small changes, please make sure any of the changes goes to main will not break anything. Otherwise, it can not be merged until this feature complete. +> **Note** If you split your pull request to small changes, please make sure any of the changes goes to main will not break anything. Otherwise, it cannot be merged until this feature complete. -- Fork and clone +### Fork and clone Fork the repository and clone the code to your local workspace. -- Branch +### Branch Changes should be made on your own fork in a new branch checked out from the `main` branch. -- Develop, Build and Test +### Develop, Build, and Test Write code on the new branch in your fork. Unit test cases should be added to cover the new code. For PR in [notation](https://github.com/notaryproject/notation), end-to-end (e2e) test cases should be added, see [e2e quick start](https://github.com/notaryproject/notation/blob/main/test/e2e/README.md) -- Keep sync with upstream +### Keep sync with upstream Once your branch gets out of sync with the `main` branch, please fetch and rebase from `main` branch. -- Commit +### Commit As Notary project repositories has integrated the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) check tool, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. Notary project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. -- Push and Create PR +### Push and Create PR - When ready for review, push your branch to your fork repository, and [create a new pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui). Description of a pull request should refer to all the issues that it addresses. Remember to put a reference to issues (such as Closes #XXX and Fixes #XXX) in commits so that the issues can be closed when the PR is merged. + When ready for review, push your branch to your fork repository, and [create a new pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui). Description of a pull request should refer to all the issues that it addresses. Remember to [link the PR to an issue using a keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) so that the issue can be closed when the PR is merged. Once your pull request has been opened it will be assigned to reviewers automatically based on CODEOWNERS. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style. @@ -132,6 +137,7 @@ The following tables define all label types used for Notary project. It is split | `duplicate` | Marks an issue or PR already exists | | `enhancement` | Marks the issue as a feature request or a PR as a feature implementation | | `keep open` | Denotes that the issue or PR should be kept open past 30 days of inactivity | +| `stale` | Marks an issue or PR stale | | `testing` | Marks an issue or PR is related to testing | | `triage` | Indicates the issue or PR needs triage | | `UX` | Marks an issue or PR is related to user experience | From 5906ba55ed913bc3508506d0f27726aaa8347ec4 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Fri, 12 May 2023 19:33:18 +0800 Subject: [PATCH 04/19] doc: update per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2c1431..62e3429 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,29 +84,33 @@ Please submit a PR broken down into small changes bit by bit. A PR consisting of ### Branch - Changes should be made on your own fork in a new branch checked out from the `main` branch. +Changes should be made on your own fork in a new branch checked out from the `main` branch. ### Develop, Build, and Test - Write code on the new branch in your fork. Unit test cases should be added to cover the new code. For PR in [notation](https://github.com/notaryproject/notation), end-to-end (e2e) test cases should be added, see [e2e quick start](https://github.com/notaryproject/notation/blob/main/test/e2e/README.md) +Write code on the new branch in your fork. Unit test cases should be added to cover the new code. For PR in [notation](https://github.com/notaryproject/notation), end-to-end (e2e) test cases should be added, see [e2e quick start](https://github.com/notaryproject/notation/blob/main/test/e2e/README.md) ### Keep sync with upstream - Once your branch gets out of sync with the `main` branch, please fetch and rebase from `main` branch. +Once your branch gets out of sync with the `main` branch, please fetch and rebase from `main` branch. ### Commit - As Notary project repositories has integrated the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) check tool, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. +As Notary project repositories has integrated the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) check tool, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. For example: - Notary project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. +```shell +git commit -s -m +``` + +Notary project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. ### Push and Create PR - When ready for review, push your branch to your fork repository, and [create a new pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui). Description of a pull request should refer to all the issues that it addresses. Remember to [link the PR to an issue using a keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) so that the issue can be closed when the PR is merged. +When ready for review, push your branch to your fork repository, and [create a new pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui). Description of a pull request should refer to all the issues that it addresses. Remember to [link the PR to an issue using a keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) so that the issue can be closed when the PR is merged. - Once your pull request has been opened it will be assigned to reviewers automatically based on CODEOWNERS. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style. +Once your pull request has been opened it will be assigned to reviewers automatically based on CODEOWNERS. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style. - Commit changes made in response to review comments to the same branch on your fork. +Commit changes made in response to review comments to the same branch on your fork. ## Contributing new features From b8ec8c4fb57464c0ffd599a409437c5754fe3c5d Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 20 May 2023 19:08:36 +0800 Subject: [PATCH 05/19] doc: update per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62e3429..dfb1afd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,7 +88,9 @@ Changes should be made on your own fork in a new branch checked out from the `ma ### Develop, Build, and Test -Write code on the new branch in your fork. Unit test cases should be added to cover the new code. For PR in [notation](https://github.com/notaryproject/notation), end-to-end (e2e) test cases should be added, see [e2e quick start](https://github.com/notaryproject/notation/blob/main/test/e2e/README.md) +Write code on the new branch in your fork. You can try to build the notation project locally by following the [Building guide](https://github.com/notaryproject/notation/blob/main/building.md) + +Unit test cases should be added to cover the new code. For PR in [notation](https://github.com/notaryproject/notation), end-to-end (e2e) test cases should be added, see [e2e quick start](https://github.com/notaryproject/notation/blob/main/test/e2e/README.md) ### Keep sync with upstream @@ -96,14 +98,14 @@ Once your branch gets out of sync with the `main` branch, please fetch and rebas ### Commit -As Notary project repositories has integrated the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) check tool, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. For example: +You should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to write commit message. As Notary project repositories enforces the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) on Pull Requests, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. Notary project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. Git has provided a `-S` flag to create a signed commit. + +An example of git commit command: ```shell -git commit -s -m +git commit -s -S -m ``` -Notary project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. - ### Push and Create PR When ready for review, push your branch to your fork repository, and [create a new pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui). Description of a pull request should refer to all the issues that it addresses. Remember to [link the PR to an issue using a keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) so that the issue can be closed when the PR is merged. From 1bdfcd4bbe5177db14c2d22774da1182fb145c0b Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 10 Jun 2023 20:44:02 +0800 Subject: [PATCH 06/19] doc: update per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfb1afd..26f3770 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,19 +4,20 @@ Welcome to the notary community. The Notary project accepts contributions via Gi ## Overview of Notary project -The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary project umbrella: - -| Repository | Description | -| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [notation](https://github.com/notaryproject/notation) | A CLI project to add signatures as standard items in the registry ecosystem, and to build a set of simple tooling for signing and verifying these signatures | -| [notation-go](https://github.com/notaryproject/notation-go) | A library project to support sign and verify artifacts and store signatures in the registry | -| [notation-core-go](https://github.com/notaryproject/notation-core-go) | A library project to support Notary signature envelope and format specific implementation | -| [notaryproject](https://github.com/notaryproject/notatryproject) | A project for Notary project requirements and specifications | -| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | A project for Notary project website | -| [.github](https://github.com/notaryproject/.github) | A project for notary project governance documents | -| [meeting-notes](https://github.com/notaryproject/meeting-notes) | A project for archived meeting notes | -| [tuf](https://github.com/notaryproject/tuf) | A project to implement the full TUF specification in a registry native way | -| [notary](https://github.com/notaryproject/notatry) | The original project, which is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry | +The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary Project umbrella in alphabetical order: + +| Repository | Description | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------| +| [.github](https://github.com/notaryproject/.github) | The repository that contains the Notary Project governance documents | +| [meeting-notes](https://github.com/notaryproject/meeting-notes) | The repository that contains archived meeting notes | +| [notary](https://github.com/notaryproject/notatry) | The repository that is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry | +| [notaryproject](https://github.com/notaryproject/notatryproject) | The repository that contains the Notary Project requirements and specifications | +| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | The repository that contains documents and styles for the Notary Project website | +| [notation](https://github.com/notaryproject/notation) | The repository that is an implementation of the Notary Project specification and provides a CLI tooling to sign and verify artifacts | +| [notation-go](https://github.com/notaryproject/notation-go) | The repository that is an implementation of the Notary Project specification and provides the library supports of signing and verifying artifacts | +| [notation-core-go](https://github.com/notaryproject/notation-core-go) | The repository that is an implementation of the Notary Project signature specification and provides the library supports | +| [roadmap](https://github.com/notaryproject/roadmap) | The repository that contains roadmap issues for the Notary Project | +| [tuf](https://github.com/notaryproject/tuf) | The repository that implements the full TUF specification in a registry native way | ## Support Channels From 3881cd38a6ab10d8f950a70f7f80e1a73b4bdb29 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 12 Jun 2023 14:26:16 +0800 Subject: [PATCH 07/19] update the Notary Project overview Signed-off-by: Yi Zha --- CONTRIBUTING.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26f3770..cf22b12 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,23 +1,23 @@ # Contributing Guidelines -Welcome to the notary community. The Notary project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted. +Welcome to the Notary Project community. The Notary Project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted. -## Overview of Notary project +## Overview of the Notary Project The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary Project umbrella in alphabetical order: -| Repository | Description | -| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------| -| [.github](https://github.com/notaryproject/.github) | The repository that contains the Notary Project governance documents | -| [meeting-notes](https://github.com/notaryproject/meeting-notes) | The repository that contains archived meeting notes | -| [notary](https://github.com/notaryproject/notatry) | The repository that is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry | -| [notaryproject](https://github.com/notaryproject/notatryproject) | The repository that contains the Notary Project requirements and specifications | -| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | The repository that contains documents and styles for the Notary Project website | -| [notation](https://github.com/notaryproject/notation) | The repository that is an implementation of the Notary Project specification and provides a CLI tooling to sign and verify artifacts | -| [notation-go](https://github.com/notaryproject/notation-go) | The repository that is an implementation of the Notary Project specification and provides the library supports of signing and verifying artifacts | -| [notation-core-go](https://github.com/notaryproject/notation-core-go) | The repository that is an implementation of the Notary Project signature specification and provides the library supports | -| [roadmap](https://github.com/notaryproject/roadmap) | The repository that contains roadmap issues for the Notary Project | -| [tuf](https://github.com/notaryproject/tuf) | The repository that implements the full TUF specification in a registry native way | +| Repository | Description | +| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [.github](https://github.com/notaryproject/.github) | This repository contains the Notary Project governance and other common documents that are shared across repositories. | +| [meeting-notes](https://github.com/notaryproject/meeting-notes) | The repository contains the archived meeting notes. | +| [notary](https://github.com/notaryproject/notatry) | This repository contains the source code for the server and the client of the TUF-based implementation. | +| [notaryproject](https://github.com/notaryproject/notatryproject) | This repository contains the Notary Project requirements, scenarios, specifications, and security audits. | +| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | This repository contains the source code and content for the [Notary Project website](https://notaryproject.dev/). | +| [notation](https://github.com/notaryproject/notation) | This repository contains the source code for the convenience CLI implementation of the Notary signing and verification flow. | +| [notation-go](https://github.com/notaryproject/notation-go) | This repository contains the source code for the convenience Golang library implementation of the Notary signing and verification flow. | +| [notation-core-go](https://github.com/notaryproject/notation-core-go) | This repository contains the source code for the convenience Golang library implementation of the Notary signing and verification flow. | +| [roadmap](https://github.com/notaryproject/roadmap) | This repository is intended for keeping track of development activities in the Notary Project. It may be retired in the future. | +| [tuf](https://github.com/notaryproject/tuf) | This repository is intended for prototyping the storage of TUF metadata in OCI-compliant registries. It is not under active development at the moment but there are plans to revive it in the future. | ## Support Channels @@ -36,7 +36,7 @@ Please refer to [Security Guide](SECURITY.md) on how to report security vulnerab ## Reporting Other Issues -It is a great way to contribute to notary project by reporting issues. Please open an issue on Github and follow the template to fill in required information. +It is a great way to contribute to the Notary Project by reporting issues. Please open an issue on Github and follow the template to fill in required information. Before opening any issue, please look up the existing issues to avoid submitting a duplication. If you found an issue that describes your problem: @@ -55,7 +55,7 @@ The issue lifecycle is mainly driven by the maintainers. 2. Triage: The maintainers will triage the issues. The results of triage could be one of the following: - Remove label `triage`, and add the issues to the correct milestone - Keep label `triage` to indicate that further triage is required - - Remove label `triage`, and labelled `wont fix` to indicate this issue is out of the scope of Notary or other reasons. + - Remove label `triage`, and labelled `wont fix` to indicate this issue is out of the scope of the Notary Project or other reasons. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it @@ -99,7 +99,7 @@ Once your branch gets out of sync with the `main` branch, please fetch and rebas ### Commit -You should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to write commit message. As Notary project repositories enforces the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) on Pull Requests, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. Notary project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. Git has provided a `-S` flag to create a signed commit. +You should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to write commit message. As the Notary Project repositories enforces the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) on Pull Requests, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. The Notary Project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. Git has provided a `-S` flag to create a signed commit. An example of git commit command: @@ -133,7 +133,7 @@ Documentation PRs will follow the same workflow as other PRs. ## Labels -The following tables define all label types used for Notary project. It is split up by category. +The following tables define all label types used for the Notary Project. It is split up by category. ### Common @@ -154,7 +154,7 @@ The following tables define all label types used for Notary project. It is split | Label | Description | | ------------------ | ------------------------------------------------------------------------ | | `help wanted` | Marks an issue needs help from the community to solve | -| `good first issue` | Marks an issue as a good starter issue for someone new to Notary project | +| `good first issue` | Marks an issue as a good starter issue for someone new to the Notary Project | | `wont fix` | Marks an issue as discussed and will not be implemented | ## Credits From a8663068043b28f5aa62c134dfd35c7bf9fa8909 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sun, 20 Aug 2023 19:01:26 +0800 Subject: [PATCH 08/19] update Notary Project overview reference Signed-off-by: Yi Zha --- CONTRIBUTING.md | 28 +--------------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf22b12..fff3acb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,6 @@ # Contributing Guidelines -Welcome to the Notary Project community. The Notary Project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted. - -## Overview of the Notary Project - -The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary Project umbrella in alphabetical order: - -| Repository | Description | -| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [.github](https://github.com/notaryproject/.github) | This repository contains the Notary Project governance and other common documents that are shared across repositories. | -| [meeting-notes](https://github.com/notaryproject/meeting-notes) | The repository contains the archived meeting notes. | -| [notary](https://github.com/notaryproject/notatry) | This repository contains the source code for the server and the client of the TUF-based implementation. | -| [notaryproject](https://github.com/notaryproject/notatryproject) | This repository contains the Notary Project requirements, scenarios, specifications, and security audits. | -| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | This repository contains the source code and content for the [Notary Project website](https://notaryproject.dev/). | -| [notation](https://github.com/notaryproject/notation) | This repository contains the source code for the convenience CLI implementation of the Notary signing and verification flow. | -| [notation-go](https://github.com/notaryproject/notation-go) | This repository contains the source code for the convenience Golang library implementation of the Notary signing and verification flow. | -| [notation-core-go](https://github.com/notaryproject/notation-core-go) | This repository contains the source code for the convenience Golang library implementation of the Notary signing and verification flow. | -| [roadmap](https://github.com/notaryproject/roadmap) | This repository is intended for keeping track of development activities in the Notary Project. It may be retired in the future. | -| [tuf](https://github.com/notaryproject/tuf) | This repository is intended for prototyping the storage of TUF metadata in OCI-compliant registries. It is not under active development at the moment but there are plans to revive it in the future. | - -## Support Channels - -Whether you are a user or contributor, official support channels include: - -- Issues for each repository. You can use [Notation issue](https://github.com/notaryproject/notation/issues) if you are not sure about which repository to be involved. -- Slack: [#notary-project](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/). Join [slack](https://slack.cncf.io/) if it is your first time using Slack. -- [Public community meetings](https://notaryproject.dev/community/#cncf-public-events-calendar) - - Catch up with [past meetings on YouTube](https://www.youtube.com/@CNCFNotary) +Welcome to the Notary Project community. The Notary Project accepts contributions via GitHub issues or pull requests. This document outlines the process to help get your contribution accepted. Please see the [Notary Project Overview](https://github.com/notaryproject/.github/blob/main/README.md) to learn about Notary Project. ## Reporting Security Issues From 78e8f2d8dc3f17cefcca53fcb149bcd9e67caed4 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 21 Aug 2023 13:58:21 +0800 Subject: [PATCH 09/19] update per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 6 +- CONTRIBUTOR_LADDER.md | 166 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTOR_LADDER.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fff3acb..9f3e104 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ The issue lifecycle is mainly driven by the maintainers. ### Stale issues or PRs -A stale issue or pull request (PR) is one that has not had any activity or updates for 60 days. When an issue or PR becomes stale, it is labelled as `stale`. Normally maintainers will comment on stale issue or PR to prompt participants to take action. Then, if no additional activity occurs after 14 days, this issue or PR will be closed. If an update/comment occur on stale issues or pull requests, the stale label will be removed and the timer will restart. +A stale issue is one that has not had any activity or updates for 60 days. A stale pull request (PR) is one that has not had any activity or updates for 45 days. When an issue or PR becomes stale, it is labelled as `stale`. Normally maintainers will comment on stale issue or PR to prompt participants to take action. Then, if no additional activity occurs after 30 days, this issue or PR will be closed. If an update/comment occur on stale issues or pull requests, the stale label will be removed and the timer will restart. ## Support requests or questions @@ -117,11 +117,11 @@ The following tables define all label types used for the Notary Project. It is s | `documentation` | Indicates the issue or PR is a documentation change | | `duplicate` | Marks an issue or PR already exists | | `enhancement` | Marks the issue as a feature request or a PR as a feature implementation | -| `keep open` | Denotes that the issue or PR should be kept open past 30 days of inactivity | +| `question` | Indicates the issue or PR need further information | | `stale` | Marks an issue or PR stale | | `testing` | Marks an issue or PR is related to testing | | `triage` | Indicates the issue or PR needs triage | -| `UX` | Marks an issue or PR is related to user experience | +| `ux` | Marks an issue or PR is related to user experience | ### Issue Specific diff --git a/CONTRIBUTOR_LADDER.md b/CONTRIBUTOR_LADDER.md new file mode 100644 index 0000000..1a4f45a --- /dev/null +++ b/CONTRIBUTOR_LADDER.md @@ -0,0 +1,166 @@ +# Contributor Ladder Template + +- [Contributor Ladder Template](#contributor-ladder-template) + - [Contributor Ladder](#contributor-ladder) + - [Contributor](#contributor) + - [Organization Member](#organization-member) + - [Org Maintainer](#org-maintainer) + - [Subproject Maintainer](#subproject-maintainer) + - [Inactivity](#inactivity) + - [Involuntary Removal or Demotion](#involuntary-removal-or-demotion) + - [Stepping Down/Emeritus Process](#stepping-downemeritus-process) + - [Contact](#contact) + - [Reference](#reference) + +## Contributor Ladder + +Hello! We are excited that you want to learn more about our project contributor ladder! This contributor ladder outlines the different contributor roles within the project, along with the responsibilities and privileges that come with them. Community members generally start at the first levels of the "ladder" and advance up it as their involvement in the project grows. Our project members are happy to help you advance along the contributor ladder. + +Each of the contributor roles below is organized into lists of three types of things. "Responsibilities" are things that a contributor is expected to do. "Requirements" are qualifications a person needs to meet to be in that role, and "Privileges" are things contributors on that level are entitled to. + +### Contributor + +Description: A Contributor contributes directly to the project and adds value to it. Contributions need not be code. People at the Contributor level may be new contributors, or they may only contribute occasionally. + +- Responsibilities include: + - Follow the CNCF CoC + - Follow the project contributing guide +- Requirements (one or several of the below): + - Report and sometimes resolve issues + - Occasionally submit PRs + - Contribute to the documentation + - Show up at meetings, takes notes + - Answer questions from other community members + - Submit feedback on issues and PRs + - Test releases and patches and submit reviews + - Run or helps run events + - Promote the project in public + - Help run the project infrastructure +- Privileges: + - Invitations to contributor events + - Eligible to become an Organization Member + +### Organization Member + +Description: An Organization Member is an established contributor who regularly participates in the project. Organization Members have privileges in both project repositories and elections, and as such are expected to act in the interests of the whole project. + +An Organization Member must meet the responsibilities and has the requirements of a Contributor, plus: + +- Responsibilities include: + - Continues to contribute regularly, as demonstrated by having at least [TODO: Number] [TODO: Metric] a year, as demonstrated by [TODO: contributor metrics source]. +- Requirements: + - Must have successful contributions to the project, including at least one of the following: + - [TODO: Number] accepted PRs, + - Reviewed [TODO: Number] PRs, + - Resolved and closed [TODO: Number] Issues, + - Become responsible for a key project management area, + - Or some equivalent combination or contribution + - Must have been contributing for at least [TODO: Number] months + - Must be actively contributing to at least one project area + - Must have two sponsors who are also Organization Members, at least one of whom does not work for the same employer + - Must enabling 2FA on their GitHub account + +- Privileges: + - May be assigned Issues and Reviews + - May give commands to CI/CD automation + - Entitled to vote in elections + - Can be added to Notary Project teams + - Can recommend other contributors to become Org Members + +The process for a Contributor to become an Organization Member is as follows: + +1. The member contributor is nominated by a sponsor, by opening an issue in the appropriate repository. +2. The second sponsor from a different employer seconds the nomination in the issue. +3. The nomination is reviewed publicly in a community meeting. All members vote for the nomination. A majority is required in order to approve the nomination. +4. Publicly announce the result in the issue, and in the [slack channel](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/). + +### Org Maintainer + +Description: Org Maintainers are very established contributors who are responsible for the entire project. As such, they have the ability to approve PRs against any area of the project, and are expected to participate in making decisions about the strategy and priorities of the project. + +A Maintainer must meet the responsibilities and requirements of a Organization Member, plus: + +- Responsibilities include: + - Reviewing at least [TODO: Number] PRs per year, especially PRs that involve multiple parts of the project + - Mentoring new members + - Writing refactoring PRs + - Participating in CNCF maintainer activities + - Determining strategy and policy for the project + - Participating in, and leading, community meetings +- Requirements + - Experience as a org member for at least [TODO: Number] months + - Demonstrates a broad knowledge of the project across multiple areas + - Is able to exercise judgment for the good of the project, independent of their employer, friends, or team + - Mentors other contributors + - Can commit to spending at least [TODO: Number] hours per month working on the project +- Additional privileges: + - Approve PRs to any area of the project + - Represent the project in public as a Maintainer + - Communicate with the CNCF on behalf of the project + - Have a vote in Maintainer decision-making meetings + +Process of becoming a maintainer: + +1. Any current Maintainer may nominate a current Organization Member to become a new Maintainer, by opening a PR against the root of the [TODO: main repository name] adding the nominee as an Approver in the OWNERS file. +2. The nominee will add a comment to the PR testifying that they agree to all requirements of becoming a Maintainer. +3. A majority of the current Maintainers must then approve the PR. + +## Subproject Maintainer + +Description: Subproject Maintainers wwn a distinct subproject or repository of the main project. Responsible for everything there. + +A Subproject Maintainer must meet the responsibilities and requirements of a Organization Member, plus: + +- Responsibilities include: + - Reviewing at least [TODO: Number] PRs per year of the subproject + - Writing refactoring PRs + - Determining strategy and policy for the subproject + - Participating in, and leading, community meetings +- Requirements + - Experience as a Org member for at least [TODO: Number] months + - Demonstrates a broad knowledge of the subproject + - Is able to exercise judgment for the good of the subproject, independent of their employer, friends, or team + - Mentors other contributors + - Can commit to spending at least [TODO: Number] hours per month working on the subproject +- Additional privileges: + - Approve PRs of the subproject + - Represent the subproject in public as a Maintainer + - Communicate with the CNCF on behalf of the subproject + - Have a vote in Maintainer decision-making meetings + +Process of becoming a subproject Maintainer: + +1. Any current Maintainer or subproject Maintainer may nominate a current Organization Member to become a new subproject Maintainer, by opening a PR against the root of the subproject adding the nominee as an Approver in the OWNERS file. +2. The nominee will add a comment to the PR testifying that they agree to all requirements of becoming a subproject Maintainer. +3. At least one of the current org maintainers, and a majority of the current subproject maintainers must then approve the PR. + +## Inactivity + +It is important for contributors to be and stay active to set an example and show commitment to the project. Inactivity is harmful to the project as it may lead to unexpected delays, contributor attrition, and a lost of trust in the project. + +- Inactivity is measured by: + - Periods of no contributions for longer than [TODO: Number] months + - Periods of no communication for longer than [TODO: Number] months +- Consequences of being inactive include: + - Involuntary removal or demotion + - Being asked to move to Emeritus status + +## Involuntary Removal or Demotion + +Involuntary removal/demotion of a contributor happens when responsibilities and requirements aren't being met. This may include repeated patterns of inactivity, extended period of inactivity, a period of failing to meet the requirements of your role, and/or a violation of the Code of Conduct. This process is important because it protects the community and its deliverables while also opens up opportunities for new contributors to step in. + +Involuntary removal or demotion is handled through a vote by a majority of the current Maintainers. + +## Stepping Down/Emeritus Process + +If and when contributors' commitment levels change, contributors can consider stepping down (moving down the contributor ladder) vs moving to emeritus status (completely stepping away from the project). + +Contact the Maintainers about changing to Emeritus status, or reducing your contributor level. + +## Contact + +- For inquiries, please reach out to [Notary Project Governance Maintainers](mailto:) + +## Reference + +- [Contributor Ladder Template](https://github.com/cncf/project-template/blob/main/CONTRIBUTOR_LADDER.md) From eea2de3f6f90b7e32faac06c1c3564b7d0d60c5d Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 21 Aug 2023 13:59:48 +0800 Subject: [PATCH 10/19] update per comments Signed-off-by: Yi Zha --- CONTRIBUTOR_LADDER.md | 166 ------------------------------------------ 1 file changed, 166 deletions(-) delete mode 100644 CONTRIBUTOR_LADDER.md diff --git a/CONTRIBUTOR_LADDER.md b/CONTRIBUTOR_LADDER.md deleted file mode 100644 index 1a4f45a..0000000 --- a/CONTRIBUTOR_LADDER.md +++ /dev/null @@ -1,166 +0,0 @@ -# Contributor Ladder Template - -- [Contributor Ladder Template](#contributor-ladder-template) - - [Contributor Ladder](#contributor-ladder) - - [Contributor](#contributor) - - [Organization Member](#organization-member) - - [Org Maintainer](#org-maintainer) - - [Subproject Maintainer](#subproject-maintainer) - - [Inactivity](#inactivity) - - [Involuntary Removal or Demotion](#involuntary-removal-or-demotion) - - [Stepping Down/Emeritus Process](#stepping-downemeritus-process) - - [Contact](#contact) - - [Reference](#reference) - -## Contributor Ladder - -Hello! We are excited that you want to learn more about our project contributor ladder! This contributor ladder outlines the different contributor roles within the project, along with the responsibilities and privileges that come with them. Community members generally start at the first levels of the "ladder" and advance up it as their involvement in the project grows. Our project members are happy to help you advance along the contributor ladder. - -Each of the contributor roles below is organized into lists of three types of things. "Responsibilities" are things that a contributor is expected to do. "Requirements" are qualifications a person needs to meet to be in that role, and "Privileges" are things contributors on that level are entitled to. - -### Contributor - -Description: A Contributor contributes directly to the project and adds value to it. Contributions need not be code. People at the Contributor level may be new contributors, or they may only contribute occasionally. - -- Responsibilities include: - - Follow the CNCF CoC - - Follow the project contributing guide -- Requirements (one or several of the below): - - Report and sometimes resolve issues - - Occasionally submit PRs - - Contribute to the documentation - - Show up at meetings, takes notes - - Answer questions from other community members - - Submit feedback on issues and PRs - - Test releases and patches and submit reviews - - Run or helps run events - - Promote the project in public - - Help run the project infrastructure -- Privileges: - - Invitations to contributor events - - Eligible to become an Organization Member - -### Organization Member - -Description: An Organization Member is an established contributor who regularly participates in the project. Organization Members have privileges in both project repositories and elections, and as such are expected to act in the interests of the whole project. - -An Organization Member must meet the responsibilities and has the requirements of a Contributor, plus: - -- Responsibilities include: - - Continues to contribute regularly, as demonstrated by having at least [TODO: Number] [TODO: Metric] a year, as demonstrated by [TODO: contributor metrics source]. -- Requirements: - - Must have successful contributions to the project, including at least one of the following: - - [TODO: Number] accepted PRs, - - Reviewed [TODO: Number] PRs, - - Resolved and closed [TODO: Number] Issues, - - Become responsible for a key project management area, - - Or some equivalent combination or contribution - - Must have been contributing for at least [TODO: Number] months - - Must be actively contributing to at least one project area - - Must have two sponsors who are also Organization Members, at least one of whom does not work for the same employer - - Must enabling 2FA on their GitHub account - -- Privileges: - - May be assigned Issues and Reviews - - May give commands to CI/CD automation - - Entitled to vote in elections - - Can be added to Notary Project teams - - Can recommend other contributors to become Org Members - -The process for a Contributor to become an Organization Member is as follows: - -1. The member contributor is nominated by a sponsor, by opening an issue in the appropriate repository. -2. The second sponsor from a different employer seconds the nomination in the issue. -3. The nomination is reviewed publicly in a community meeting. All members vote for the nomination. A majority is required in order to approve the nomination. -4. Publicly announce the result in the issue, and in the [slack channel](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/). - -### Org Maintainer - -Description: Org Maintainers are very established contributors who are responsible for the entire project. As such, they have the ability to approve PRs against any area of the project, and are expected to participate in making decisions about the strategy and priorities of the project. - -A Maintainer must meet the responsibilities and requirements of a Organization Member, plus: - -- Responsibilities include: - - Reviewing at least [TODO: Number] PRs per year, especially PRs that involve multiple parts of the project - - Mentoring new members - - Writing refactoring PRs - - Participating in CNCF maintainer activities - - Determining strategy and policy for the project - - Participating in, and leading, community meetings -- Requirements - - Experience as a org member for at least [TODO: Number] months - - Demonstrates a broad knowledge of the project across multiple areas - - Is able to exercise judgment for the good of the project, independent of their employer, friends, or team - - Mentors other contributors - - Can commit to spending at least [TODO: Number] hours per month working on the project -- Additional privileges: - - Approve PRs to any area of the project - - Represent the project in public as a Maintainer - - Communicate with the CNCF on behalf of the project - - Have a vote in Maintainer decision-making meetings - -Process of becoming a maintainer: - -1. Any current Maintainer may nominate a current Organization Member to become a new Maintainer, by opening a PR against the root of the [TODO: main repository name] adding the nominee as an Approver in the OWNERS file. -2. The nominee will add a comment to the PR testifying that they agree to all requirements of becoming a Maintainer. -3. A majority of the current Maintainers must then approve the PR. - -## Subproject Maintainer - -Description: Subproject Maintainers wwn a distinct subproject or repository of the main project. Responsible for everything there. - -A Subproject Maintainer must meet the responsibilities and requirements of a Organization Member, plus: - -- Responsibilities include: - - Reviewing at least [TODO: Number] PRs per year of the subproject - - Writing refactoring PRs - - Determining strategy and policy for the subproject - - Participating in, and leading, community meetings -- Requirements - - Experience as a Org member for at least [TODO: Number] months - - Demonstrates a broad knowledge of the subproject - - Is able to exercise judgment for the good of the subproject, independent of their employer, friends, or team - - Mentors other contributors - - Can commit to spending at least [TODO: Number] hours per month working on the subproject -- Additional privileges: - - Approve PRs of the subproject - - Represent the subproject in public as a Maintainer - - Communicate with the CNCF on behalf of the subproject - - Have a vote in Maintainer decision-making meetings - -Process of becoming a subproject Maintainer: - -1. Any current Maintainer or subproject Maintainer may nominate a current Organization Member to become a new subproject Maintainer, by opening a PR against the root of the subproject adding the nominee as an Approver in the OWNERS file. -2. The nominee will add a comment to the PR testifying that they agree to all requirements of becoming a subproject Maintainer. -3. At least one of the current org maintainers, and a majority of the current subproject maintainers must then approve the PR. - -## Inactivity - -It is important for contributors to be and stay active to set an example and show commitment to the project. Inactivity is harmful to the project as it may lead to unexpected delays, contributor attrition, and a lost of trust in the project. - -- Inactivity is measured by: - - Periods of no contributions for longer than [TODO: Number] months - - Periods of no communication for longer than [TODO: Number] months -- Consequences of being inactive include: - - Involuntary removal or demotion - - Being asked to move to Emeritus status - -## Involuntary Removal or Demotion - -Involuntary removal/demotion of a contributor happens when responsibilities and requirements aren't being met. This may include repeated patterns of inactivity, extended period of inactivity, a period of failing to meet the requirements of your role, and/or a violation of the Code of Conduct. This process is important because it protects the community and its deliverables while also opens up opportunities for new contributors to step in. - -Involuntary removal or demotion is handled through a vote by a majority of the current Maintainers. - -## Stepping Down/Emeritus Process - -If and when contributors' commitment levels change, contributors can consider stepping down (moving down the contributor ladder) vs moving to emeritus status (completely stepping away from the project). - -Contact the Maintainers about changing to Emeritus status, or reducing your contributor level. - -## Contact - -- For inquiries, please reach out to [Notary Project Governance Maintainers](mailto:) - -## Reference - -- [Contributor Ladder Template](https://github.com/cncf/project-template/blob/main/CONTRIBUTOR_LADDER.md) From 846e4b7a459279c0db550277410b5b6823ff4ffa Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 21 Aug 2023 14:32:15 +0800 Subject: [PATCH 11/19] upate per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f3e104..27b871e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,7 +28,7 @@ The issue lifecycle is mainly driven by the maintainers. - After an issue is created, it will be labelled `bug` or `enhancement`, and `triage`. 2. Triage: The maintainers will triage the issues. The results of triage could be one of the following: - Remove label `triage`, and add the issues to the correct milestone - - Keep label `triage` to indicate that further triage is required + - Remove label `triage`, and labelled `question` to indicate this issue need further information - Remove label `triage`, and labelled `wont fix` to indicate this issue is out of the scope of the Notary Project or other reasons. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation @@ -125,11 +125,11 @@ The following tables define all label types used for the Notary Project. It is s ### Issue Specific -| Label | Description | -| ------------------ | ------------------------------------------------------------------------ | -| `help wanted` | Marks an issue needs help from the community to solve | +| Label | Description | +| ------------------ | ---------------------------------------------------------------------------- | +| `help wanted` | Marks an issue needs help from the community to solve | | `good first issue` | Marks an issue as a good starter issue for someone new to the Notary Project | -| `wont fix` | Marks an issue as discussed and will not be implemented | +| `wont fix` | Marks an issue as discussed and will not be implemented | ## Credits From a738795a3c1dcc62240b737b4bd6a1cba9c10d37 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 21 Aug 2023 19:14:04 +0800 Subject: [PATCH 12/19] update per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27b871e..276ab6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,6 +37,8 @@ The issue lifecycle is mainly driven by the maintainers. - Close the issue once PRs are merged - Close the issue once the author accepts the `wont fix` decision +After issues labelled `question` are clarified with further information, these issues could be added to the correct milestone or labelled `wont fix`. + ### Stale issues or PRs A stale issue is one that has not had any activity or updates for 60 days. A stale pull request (PR) is one that has not had any activity or updates for 45 days. When an issue or PR becomes stale, it is labelled as `stale`. Normally maintainers will comment on stale issue or PR to prompt participants to take action. Then, if no additional activity occurs after 30 days, this issue or PR will be closed. If an update/comment occur on stale issues or pull requests, the stale label will be removed and the timer will restart. From 10d78b4db7fcd1c26f36176853a8b64cd80e9ae3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 23 Aug 2023 13:08:52 +0800 Subject: [PATCH 13/19] update per comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 276ab6b..374fd33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,9 +26,9 @@ The issue lifecycle is mainly driven by the maintainers. 1. Issue creation: - After an issue is created, it will be labelled `bug` or `enhancement`, and `triage`. -2. Triage: The maintainers will triage the issues. The results of triage could be one of the following: +2. Triage: The maintainers will triage the issues on a regular basis. The results of triage could be one of the following: - Remove label `triage`, and add the issues to the correct milestone - - Remove label `triage`, and labelled `question` to indicate this issue need further information + - Remove label `triage`, and labelled `question` to indicate this issue need further information. After this issue is clarified with further information, it could be added to the correct milestone or labelled `wont fix`. - Remove label `triage`, and labelled `wont fix` to indicate this issue is out of the scope of the Notary Project or other reasons. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation @@ -37,12 +37,20 @@ The issue lifecycle is mainly driven by the maintainers. - Close the issue once PRs are merged - Close the issue once the author accepts the `wont fix` decision -After issues labelled `question` are clarified with further information, these issues could be added to the correct milestone or labelled `wont fix`. - ### Stale issues or PRs A stale issue is one that has not had any activity or updates for 60 days. A stale pull request (PR) is one that has not had any activity or updates for 45 days. When an issue or PR becomes stale, it is labelled as `stale`. Normally maintainers will comment on stale issue or PR to prompt participants to take action. Then, if no additional activity occurs after 30 days, this issue or PR will be closed. If an update/comment occur on stale issues or pull requests, the stale label will be removed and the timer will restart. +## Milestones + +The Notary Project uses [milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) to track progress on groups of issues or pull requests in a repository. The following table defines the milestones that used by the Notary Project. + +| Milestone | Description | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `discuss` | This milestone includes issues or PRs that require discussion before they can be added to the correct milestone. | +| `future` | This milestone includes issues or PRs that are valuable but are not currently planned for release. | +| `` | This milestone includes issues or PRs that are planned for a specific release. The format is `vX.Y.Z`, For example, `v1.1.0`, `v1.2.0`. See [Release Versioning](https://github.com/notaryproject/notation/blob/main/RELEASE_MANAGEMENT.md#release-versioning) for details. | + ## Support requests or questions Please use slack channel for support requests or questions. Issues could be created accordingly if it is a bug or enhancement. @@ -119,10 +127,8 @@ The following tables define all label types used for the Notary Project. It is s | `documentation` | Indicates the issue or PR is a documentation change | | `duplicate` | Marks an issue or PR already exists | | `enhancement` | Marks the issue as a feature request or a PR as a feature implementation | -| `question` | Indicates the issue or PR need further information | | `stale` | Marks an issue or PR stale | | `testing` | Marks an issue or PR is related to testing | -| `triage` | Indicates the issue or PR needs triage | | `ux` | Marks an issue or PR is related to user experience | ### Issue Specific @@ -131,6 +137,8 @@ The following tables define all label types used for the Notary Project. It is s | ------------------ | ---------------------------------------------------------------------------- | | `help wanted` | Marks an issue needs help from the community to solve | | `good first issue` | Marks an issue as a good starter issue for someone new to the Notary Project | +| `question` | Indicates the issue need further information | +| `triage` | Indicates the issue needs triage | | `wont fix` | Marks an issue as discussed and will not be implemented | ## Credits From 0e6d30b15f074aae2efd59777cfa0dcdbcc77f9f Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 23 Aug 2023 13:42:02 +0800 Subject: [PATCH 14/19] update recommending ssh method Signed-off-by: Yi Zha --- CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 374fd33..7328197 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,7 +57,7 @@ Please use slack channel for support requests or questions. Issues could be crea ## Contributing Workflow -PR are always welcome, even if they only contain small fixes like typos or a few lines of code. If there will be a significant effort, please document it as an issue and get a discussion going before starting to work on it. +PR are always welcome, even if they only contain small fixes like typos or a few lines of code. If there will be a significant effort, please document it as an issue and get a discussion going before starting to work on it.- Please submit a PR broken down into small changes bit by bit. A PR consisting of a lot of features and code changes may be hard to review. It is recommended to submit PRs in an incremental fashion. @@ -83,9 +83,11 @@ Once your branch gets out of sync with the `main` branch, please fetch and rebas ### Commit -You should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to write commit message. As the Notary Project repositories enforces the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) on Pull Requests, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. The Notary Project repositories require signed commits, please refer to [commit signatures verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. Git has provided a `-S` flag to create a signed commit. +You should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to write commit message. As the Notary Project repositories enforces the [DCO (Developer Certificate of Origin)](https://github.com/apps/dco) on Pull Requests, contributors are required to sign off that they adhere to those requirements by adding a `Signed-off-by` line to the commit messages. Git has even provided a `-s` command line option to append that automatically to your commit messages, please use it when you commit your changes. -An example of git commit command: +The Notary Project repositories require signed commits, please refer to [SSH commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#ssh-commit-signature-verification) on signing commits using SSH as it is easy to set up. You can find other methods to sign commits in the document [commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). Git has provided a `-S` flag to create a signed commit. + +An example of `git commit` command: ```shell git commit -s -S -m From 2edce63503ca71c8179a02d005d73493793ec937 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sun, 10 Sep 2023 14:33:41 +0800 Subject: [PATCH 15/19] update per Pritesh's comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7328197..8f4b59c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,21 @@ # Contributing Guidelines -Welcome to the Notary Project community. The Notary Project accepts contributions via GitHub issues or pull requests. This document outlines the process to help get your contribution accepted. Please see the [Notary Project Overview](https://github.com/notaryproject/.github/blob/main/README.md) to learn about Notary Project. +This document offers an overview of the process for users to contribute by either opening a pull request or reporting an issue. For more more information about the Notary Project, please refer to the [Notary Project Overview](https://github.com/notaryproject/.github/blob/main/README.md). -## Reporting Security Issues +## Reporting a Security Issue -> **Warning** If you are reporting a security vulnerability, Please DO NOT file a public issue. +> **Warning** If you are reporting a security vulnerability, Please DO NOT open a public issue. Please refer to [Security Guide](SECURITY.md) on how to report security vulnerabilities. -## Reporting Other Issues +## Reporting an Issue -It is a great way to contribute to the Notary Project by reporting issues. Please open an issue on Github and follow the template to fill in required information. +Reporting an issue is a great way to contribute. Please open an issue on Github with required information. -Before opening any issue, please look up the existing issues to avoid submitting a duplication. If you found an issue that describes your problem: +Prior to opening a new issue, we kindly request that you check the existing issues to prevent duplicate submissions. In the event that you come across an issue that aligns with your problem please do following: -- Please read other user comments first to confirm if they have experienced the same issue. Keep in mind that a given error condition might be indicative of different problems. You may also find a workaround in the comments -- To receive updates on an issue, simply click the 'subscribe' button +- Carefully review the issue description and comments to validate that your issue aligns with a similar problem. It's important to note that a specific error could potentially be associated with various issues. Additionally, you might discover a potential solution or workaround in the comments section +- To receive notifications regarding an issue, just click the 'subscribe' button - Please only comment if you have new, technical, and relevant information to add to the case. Issues will be marked with different labels for different purpose, see [Labels](#labels) for details. @@ -26,10 +26,10 @@ The issue lifecycle is mainly driven by the maintainers. 1. Issue creation: - After an issue is created, it will be labelled `bug` or `enhancement`, and `triage`. -2. Triage: The maintainers will triage the issues on a regular basis. The results of triage could be one of the following: - - Remove label `triage`, and add the issues to the correct milestone - - Remove label `triage`, and labelled `question` to indicate this issue need further information. After this issue is clarified with further information, it could be added to the correct milestone or labelled `wont fix`. - - Remove label `triage`, and labelled `wont fix` to indicate this issue is out of the scope of the Notary Project or other reasons. +2. Triage: The maintainers will triage the issues on a regular basis. The results of triage will be one of the following: + - Remove label `triage`, and add the issues to the correct milestone. + - Remove the `triage` label and apply the `question` label to indicate that this issue requires additional information. Once this issue has been clarified with the necessary details, it can then be assigned to the appropriate milestone or labeled as `wont fix`. + - Remove the `triage` label and assign the `wont fix` label to signify that this issue falls outside the scope of the Notary Project or for other relevant reasons. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it @@ -39,7 +39,7 @@ The issue lifecycle is mainly driven by the maintainers. ### Stale issues or PRs -A stale issue is one that has not had any activity or updates for 60 days. A stale pull request (PR) is one that has not had any activity or updates for 45 days. When an issue or PR becomes stale, it is labelled as `stale`. Normally maintainers will comment on stale issue or PR to prompt participants to take action. Then, if no additional activity occurs after 30 days, this issue or PR will be closed. If an update/comment occur on stale issues or pull requests, the stale label will be removed and the timer will restart. +A stale issue is one that remains inactive or without updates for a period of 60 days. A stale pull request (PR) is one that remains inactive or without updates for a period of 45 days. When an issue or PR becomes stale, it is labelled as `stale`. Normally maintainers will comment on stale issue or PR to prompt participants to take action. If there is no activity for additional 30 days, this issue or PR will be closed. If an update/comment occur on stale issues or pull requests, the stale label will be removed and the timer will restart. ## Milestones From b5c43a3facb84e9402a9e2c65d1342fad298988e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 18 Sep 2023 12:47:49 +0800 Subject: [PATCH 16/19] update per shiwei's comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f4b59c..7df4015 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,8 @@ This document offers an overview of the process for users to contribute by eithe ## Reporting a Security Issue -> **Warning** If you are reporting a security vulnerability, Please DO NOT open a public issue. +> [!Warning] +> If you are reporting a security vulnerability, Please DO NOT open a public issue. Please refer to [Security Guide](SECURITY.md) on how to report security vulnerabilities. @@ -34,8 +35,10 @@ The issue lifecycle is mainly driven by the maintainers. - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it 4. Issue closure - - Close the issue once PRs are merged - - Close the issue once the author accepts the `wont fix` decision + - Close the issue once PRs are merged. + - Close the issue once the author accepts the `wont fix` decision. + - Close the issue if a bug cannot be reproduced with the author's agreement. Create a new issue if this bug is reproduced in the future. + - Transform the issue to GitHub discussion with the author's agreement, if an issue contains open-ended conversations that don’t necessarily have a specific goal or outcome in mind. ### Stale issues or PRs @@ -57,7 +60,7 @@ Please use slack channel for support requests or questions. Issues could be crea ## Contributing Workflow -PR are always welcome, even if they only contain small fixes like typos or a few lines of code. If there will be a significant effort, please document it as an issue and get a discussion going before starting to work on it.- +PRs are always welcome, even if they only contain small fixes like typos or a few lines of code. If there will be a significant effort, please document it as an issue and get a discussion going before starting to work on it.- Please submit a PR broken down into small changes bit by bit. A PR consisting of a lot of features and code changes may be hard to review. It is recommended to submit PRs in an incremental fashion. From f0dc4e5a21a2a680ece075d3193cda22d58ddb60 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 6 Nov 2023 12:06:25 +0800 Subject: [PATCH 17/19] update closing issues Signed-off-by: Yi Zha --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7df4015..27064e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,11 +34,11 @@ The issue lifecycle is mainly driven by the maintainers. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it -4. Issue closure - - Close the issue once PRs are merged. - - Close the issue once the author accepts the `wont fix` decision. - - Close the issue if a bug cannot be reproduced with the author's agreement. Create a new issue if this bug is reproduced in the future. - - Transform the issue to GitHub discussion with the author's agreement, if an issue contains open-ended conversations that don’t necessarily have a specific goal or outcome in mind. +4. Issue closure: Follow the [guideance](https://docs.github.com/en/issues/tracking-your-work-with-issues/closing-an-issue) + - Close as completed once PRs are merged. + - Close as completed once the author accepts the `wont fix` decision. + - Close as not planned if a bug cannot be reproduced with the author's agreement. Create a new issue if this bug is reproduced in the future. + - Close as not planned by transforming the issue to GitHub discussion with the author's agreement, if an issue contains open-ended conversations that don’t necessarily have a specific goal or outcome in mind. ### Stale issues or PRs From 3ab10b61bccc93b305c56addbeeed717138eb702 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 9 Nov 2023 14:03:06 +0800 Subject: [PATCH 18/19] update a typo Signed-off-by: Yi Zha --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27064e0..920d1a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ The issue lifecycle is mainly driven by the maintainers. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it -4. Issue closure: Follow the [guideance](https://docs.github.com/en/issues/tracking-your-work-with-issues/closing-an-issue) +4. Issue closure: Follow the [guidance](https://docs.github.com/en/issues/tracking-your-work-with-issues/closing-an-issue) - Close as completed once PRs are merged. - Close as completed once the author accepts the `wont fix` decision. - Close as not planned if a bug cannot be reproduced with the author's agreement. Create a new issue if this bug is reproduced in the future. From bf7834d6980cf6c3a2f1ee6296f3848ed64c3c86 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 27 Dec 2023 13:52:19 +0800 Subject: [PATCH 19/19] upate per Toddy's comments Signed-off-by: Yi Zha --- CONTRIBUTING.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 920d1a7..4f5b6dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,18 +27,16 @@ The issue lifecycle is mainly driven by the maintainers. 1. Issue creation: - After an issue is created, it will be labelled `bug` or `enhancement`, and `triage`. -2. Triage: The maintainers will triage the issues on a regular basis. The results of triage will be one of the following: +2. Triage: The maintainers will triage the issues weekly. The results of triage will be one of the following: - Remove label `triage`, and add the issues to the correct milestone. - - Remove the `triage` label and apply the `question` label to indicate that this issue requires additional information. Once this issue has been clarified with the necessary details, it can then be assigned to the appropriate milestone or labeled as `wont fix`. + - Remove the `triage` label and apply the `need information` label to indicate that this issue requires additional information. Once this issue has been clarified with the necessary details, it can then be assigned to the appropriate milestone or labeled as `wont fix`. - Remove the `triage` label and assign the `wont fix` label to signify that this issue falls outside the scope of the Notary Project or for other relevant reasons. 3. Development: - An issue labelled `enhancement` normally require solution proposal and spec updates if needed before implementation - An issue that is labeled as `enhancement` or `bug` should be connected to the PR that resolves it -4. Issue closure: Follow the [guidance](https://docs.github.com/en/issues/tracking-your-work-with-issues/closing-an-issue) - - Close as completed once PRs are merged. - - Close as completed once the author accepts the `wont fix` decision. - - Close as not planned if a bug cannot be reproduced with the author's agreement. Create a new issue if this bug is reproduced in the future. - - Close as not planned by transforming the issue to GitHub discussion with the author's agreement, if an issue contains open-ended conversations that don’t necessarily have a specific goal or outcome in mind. +4. Issue closure: According to the [guidance](https://docs.github.com/en/issues/tracking-your-work-with-issues/closing-an-issue), there are two reasons for closing an issue: `Close as completed` (default reason) and `Close as not planned`. + - Use `Close as completed` if the issue is fixed, resolved, or done. + - Use `Close as not planned` if the author accepts the wont fix decision, or if the issue cannot be reproduced, duplicated, or is stale. ### Stale issues or PRs @@ -50,9 +48,9 @@ The Notary Project uses [milestones](https://docs.github.com/en/issues/using-lab | Milestone | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `discuss` | This milestone includes issues or PRs that require discussion before they can be added to the correct milestone. | -| `future` | This milestone includes issues or PRs that are valuable but are not currently planned for release. | -| `` | This milestone includes issues or PRs that are planned for a specific release. The format is `vX.Y.Z`, For example, `v1.1.0`, `v1.2.0`. See [Release Versioning](https://github.com/notaryproject/notation/blob/main/RELEASE_MANAGEMENT.md#release-versioning) for details. | +| `in discussion` | This milestone includes issues or PRs that require discussion before they can be added to the correct milestone. | +| `backlog` | This milestone includes issues or PRs that are valuable but are not currently planned for release. | +| `` | This milestone includes issues or PRs that are planned for a specific release. The format is `vX.Y.Z`, For example, `v1.1.0`, `v1.2.0`. See [Release Versioning](https://github.com/notaryproject/notation/blob/v1.0.1/RELEASE_MANAGEMENT.md#release-versioning) for details. | ## Support requests or questions @@ -142,7 +140,7 @@ The following tables define all label types used for the Notary Project. It is s | ------------------ | ---------------------------------------------------------------------------- | | `help wanted` | Marks an issue needs help from the community to solve | | `good first issue` | Marks an issue as a good starter issue for someone new to the Notary Project | -| `question` | Indicates the issue need further information | +| `need information` | Indicates the issue need further information | | `triage` | Indicates the issue needs triage | | `wont fix` | Marks an issue as discussed and will not be implemented |