diff --git a/community/CONTRIBUTING.md b/community/CONTRIBUTING.md index df07aae0d..8b23185e0 100644 --- a/community/CONTRIBUTING.md +++ b/community/CONTRIBUTING.md @@ -4,30 +4,30 @@ So, you want to hack on Knative? Yay! The following sections outline the process all changes to the Knative repositories go through. All changes, regardless of whether they are from -newcomers to the community or from the core team follow the same process and -are given the same level of review. +newcomers to the community or from the core team follow the same process and are +given the same level of review. -* [Working groups](#working-groups) -* [Code of conduct](#code-of-conduct) -* [Team values](#team-values) -* [Contributor license agreements](#contributor-license-agreements) -* [Design documents](#design-documents) -* [Contributing a feature](#contributing-a-feature) -* [Setting up to contribute to Knative](#setting-up-to-contribute-to-knative) -* [Pull requests](#pull-requests) -* [Issues](#issues) +- [Working groups](#working-groups) +- [Code of conduct](#code-of-conduct) +- [Team values](#team-values) +- [Contributor license agreements](#contributor-license-agreements) +- [Design documents](#design-documents) +- [Contributing a feature](#contributing-a-feature) +- [Setting up to contribute to Knative](#setting-up-to-contribute-to-knative) +- [Pull requests](#pull-requests) +- [Issues](#issues) ## Working groups -The Knative community is organized into a set of [working -groups](WORKING-GROUPS.md). Any contribution to Knative should be started by -first engaging with the appropriate working group. +The Knative community is organized into a set of +[working groups](WORKING-GROUPS.md). Any contribution to Knative should be +started by first engaging with the appropriate working group. ## Code of conduct -All members of the Knative community must abide by the [Code of -Conduct](CODE-OF-CONDUCT.md). Only by respecting each other can we develop a -productive, collaborative community. +All members of the Knative community must abide by the +[Code of Conduct](CODE-OF-CONDUCT.md). Only by respecting each other can we +develop a productive, collaborative community. ## Team values @@ -47,64 +47,68 @@ permission to use and redistribute your contributions as part of the project. ## Design documents -Any substantial design deserves a design document. Design documents are -written with Google Docs and should be shared with the community by adding -the doc to our +Any substantial design deserves a design document. Design documents are written +with Google Docs and should be shared with the community by adding the doc to +our [Team Drive](https://drive.google.com/corp/drive/folders/0APnJ_hRs30R2Uk9PVA) and sending an email to the appropriate working group's mailing list to let -people know the doc is there. To get write access to the drive, you'll need -to be a [member](ROLES.md#member) of the Knative organization. +people know the doc is there. To get write access to the drive, you'll need to +be a [member](ROLES.md#member) of the Knative organization. We do not yet have a common design document template(TODO). The team drive is shared with the +[knative-users@](https://groups.google.com/forum/#!forum/knative-users) and [knative-dev@](https://groups.google.com/forum/#!forum/knative-dev) Google -group for editing and commenting. If you're not part of that group, the -first time you try to access the team drive or a specific doc, you'll be -asked to request permission. This permission will always be granted and we -do our best to grant access as fast as we can, but there is a human involved -there, so please forgive any delays. +groups for reading and editing, respectively. Access to +[knative-users@](https://groups.google.com/forum/#!forum/knative-users) is +unlimited, while +[knative-dev@](https://groups.google.com/forum/#!forum/knative-dev) requires +human review. If you're not part of one of those groups, the first time you try +to access the team drive or a specific doc, you'll be asked to request +permission. Please join one of the above groups (you can join knative-users and +later join knative-dev if you want immediate access). ## Contributing a feature In order to contribute a feature to Knative you'll need to go through the following steps: -* Discuss your idea with the appropriate [working groups](WORKING-GROUPS.md) - on the working group's mailing list. +- Discuss your idea with the appropriate [working groups](WORKING-GROUPS.md) on + the working group's mailing list. -* Once there is general agreement that the feature is useful, [create a GitHub - issue](https://github.com/knative/docs/issues/new) to track the discussion. - The issue should include information about the requirements and use cases - that it is trying to address. Include a discussion of the proposed design - and technical details of the implementation in the issue. +- Once there is general agreement that the feature is useful, + [create a GitHub issue](https://github.com/knative/docs/issues/new) to track + the discussion. The issue should include information about the requirements + and use cases that it is trying to address. Include a discussion of the + proposed design and technical details of the implementation in the issue. -* If the feature is substantial enough: +- If the feature is substantial enough: - * Working group leads will ask for a design document as outlined in - [design documents](#design-documents). Create the design document and - add a link to it in the GitHub issue. Don't forget to send a note to the - working group to let everyone know your document is ready for review. + - Working group leads will ask for a design document as outlined in + [design documents](#design-documents). Create the design document and add a + link to it in the GitHub issue. Don't forget to send a note to the working + group to let everyone know your document is ready for review. - * Depending on the breadth of the design and how contentious it is, the - working group leads may decide the feature needs to be discussed in one - or more working group meetings before being approved. + - Depending on the breadth of the design and how contentious it is, the + working group leads may decide the feature needs to be discussed in one or + more working group meetings before being approved. - * Once the major technical issues are resolved and agreed upon, post a - note with the design decision and the general execution plan to the - working group's mailing list and on the feature's issue. + - Once the major technical issues are resolved and agreed upon, post a note + with the design decision and the general execution plan to the working + group's mailing list and on the feature's issue. -* Submit PRs to [knative/serving](https://github.com/knative/serving/pulls) - with your code changes. +- Submit PRs to [knative/serving](https://github.com/knative/serving/pulls) with + your code changes. -* Submit PRs to knative/serving with user documentation for your feature, - including usage examples when possible. Add documentation to - [knative/docs/serving](https://github.com/knative/docs/tree/master/serving). - +- Submit PRs to knative/serving with user documentation for your feature, + including usage examples when possible. Add documentation to + [knative/docs/serving](https://github.com/knative/docs/tree/master/serving). + -*Note that we prefer bite-sized PRs instead of giant monster PRs. It's therefore +_Note that we prefer bite-sized PRs instead of giant monster PRs. It's therefore preferable if you can introduce large features in small, individually-reviewable -PRs that build on top of one another.* +PRs that build on top of one another._ If you would like to skip the process of submitting an issue and instead would prefer to just submit a pull request with your desired code changes then that's @@ -117,8 +121,8 @@ so the choice is up to you. Check out this [README](https://github.com/knative/serving/blob/master/README.md) to learn -about the Knative source base and setting up your [development -environment](https://github.com/knative/serving/blob/master/DEVELOPMENT.md). +about the Knative source base and setting up your +[development environment](https://github.com/knative/serving/blob/master/DEVELOPMENT.md). ## Pull requests @@ -128,14 +132,14 @@ active, and hopefully prevents duplicated efforts. To submit a proposed change: -* Fork the affected repository. -* Create a new branch for your changes. -* Develop the code/fix. -* Add new test cases. In the case of a bug fix, the tests should fail without - your code changes. For new features try to cover as many variants as - reasonably possible. -* Modify the documentation as necessary. -* Verify all CI status checks pass, and work to make them pass if failing. +- Fork the affected repository. +- Create a new branch for your changes. +- Develop the code/fix. +- Add new test cases. In the case of a bug fix, the tests should fail without + your code changes. For new features try to cover as many variants as + reasonably possible. +- Modify the documentation as necessary. +- Verify all CI status checks pass, and work to make them pass if failing. The general rule is that all PRs should be 100% complete - meaning they should include all test cases and documentation changes related to the change. A @@ -143,14 +147,17 @@ significant exception is work-in-progress PRs. These should be indicated by a `[WIP]` prefix in the PR title. WIP PRs should not be merged as long as they are marked WIP. -When ready, if you have not already done so, sign a [contributor license -agreement](#contributor-license-agreements) and submit the PR. +When ready, if you have not already done so, sign a +[contributor license agreement](#contributor-license-agreements) and submit the +PR. -This project uses [Prow](https://github.com/kubernetes/test-infra/tree/master/prow) -to assign reviewers to the PR, set labels, run tests automatically, and so forth. +This project uses +[Prow](https://github.com/kubernetes/test-infra/tree/master/prow) to assign +reviewers to the PR, set labels, run tests automatically, and so forth. See [Reviewing and Merging Pull Requests](REVIEWING.md) for the PR review and -merge process used for Knative and for more information about [Prow](./REVIEWING.md#prow). +merge process used for Knative and for more information about +[Prow](./REVIEWING.md#prow). ## Issues @@ -158,47 +165,55 @@ GitHub issues can be used to report bugs or submit feature requests. When reporting a bug please include the following key pieces of information: -* The version of the project you were using (version number, git commit, etc) -* Operating system you are using -* The exact, minimal, steps needed to reproduce the issue. Submitting a 5 line - script will get a much faster response from the team than one that's - hundreds of lines long. +- The version of the project you were using (version number, git commit, etc) +- Operating system you are using +- The exact, minimal, steps needed to reproduce the issue. Submitting a 5 line + script will get a much faster response from the team than one that's hundreds + of lines long. ## Third-party code -* All third-party code must be placed in `vendor/` or `third_party/` folders. -* `vendor/` folder is managed by [dep](https://github.com/golang/dep) and stores -the source code of third-party Go dependencies. `vendor/` folder should not be -modified manually. -* Other third-party code belongs in `third_party/` folder. -* Third-party code must include licenses. -A non-exclusive list of code that must be places in `vendor/` and `third_party/`: -* Open source, free software, or commercially-licensed code. -* Tools or libraries or protocols that are open source, free software, or commercially licensed. -* Derivative works of third-party code. -* Excerpts from third-party code. +- All third-party code must be placed in `vendor/` or `third_party/` folders. +- `vendor/` folder is managed by [dep](https://github.com/golang/dep) and stores + the source code of third-party Go dependencies. `vendor/` folder should not be + modified manually. +- Other third-party code belongs in `third_party/` folder. +- Third-party code must include licenses. + +A non-exclusive list of code that must be places in `vendor/` and +`third_party/`: + +- Open source, free software, or commercially-licensed code. +- Tools or libraries or protocols that are open source, free software, or + commercially licensed. +- Derivative works of third-party code. +- Excerpts from third-party code. ### Adding a new third-party dependency to `third_party/` folder -* Create a sub-folder under `third_party/` for each component. -* In each sub-folder, make sure there is a file called LICENSE which contains the appropriate - license text for the dependency. If one doesn't exist then create it. More details on this below. -* Check in a pristine copy of the code with LICENSE and METADATA files. - You do not have to include unused files, and you can move or rename files if necessary, - but do not modify the contents of any files yet. -* Once the pristine copy is merged into master, you may modify the code. + +- Create a sub-folder under `third_party/` for each component. +- In each sub-folder, make sure there is a file called LICENSE which contains + the appropriate license text for the dependency. If one doesn't exist then + create it. More details on this below. +- Check in a pristine copy of the code with LICENSE and METADATA files. You do + not have to include unused files, and you can move or rename files if + necessary, but do not modify the contents of any files yet. +- Once the pristine copy is merged into master, you may modify the code. ### LICENSE -The license for the code must be in a file named LICENSE. If it was distributed like that, -you're good. If not, you need to make LICENSE be a file containing the full text of the license. -If there's another file in the distribution with the license in it, rename it to LICENSE -(e.g., rename a LICENSE.txt or COPYING file to LICENSE). If the license is only available in -the comments or at a URL, extract and copy the text of the license into LICENSE. -You may optionally document the generation of the LICENSE file in the local_modifications -field of the METADATA file. +The license for the code must be in a file named LICENSE. If it was distributed +like that, you're good. If not, you need to make LICENSE be a file containing +the full text of the license. If there's another file in the distribution with +the license in it, rename it to LICENSE (e.g., rename a LICENSE.txt or COPYING +file to LICENSE). If the license is only available in the comments or at a URL, +extract and copy the text of the license into LICENSE. -If there are multiple licenses for the code, put the text of all the licenses into LICENSE -along with separators and comments as to the applications. +You may optionally document the generation of the LICENSE file in the +local_modifications field of the METADATA file. + +If there are multiple licenses for the code, put the text of all the licenses +into LICENSE along with separators and comments as to the applications. --- diff --git a/community/ROLES.md b/community/ROLES.md index d96d1826f..7059fb3c5 100644 --- a/community/ROLES.md +++ b/community/ROLES.md @@ -34,7 +34,7 @@ table describes: Collaborator Casual contributor to the project - n/a + Join [knative-users@](https://groups.google.com/forum/#!forum/knative-users) to get access to the team drive.

Can submit PRs

Commenting permission on the Knative Team drive

@@ -115,7 +115,9 @@ the PR bot. * Working on some contribution to the project that would benefit from the ability to have PRs or Issues to be assigned to the contributor -* Sponsored by 1 member +* Join [knative-users@](https://groups.google.com/forum/#!forum/knative-users) + unrestricted join permissions; this grants read access to documents in the + Team Drive ## Member diff --git a/community/WORKING-GROUPS.md b/community/WORKING-GROUPS.md index 1d59853b4..aa1c349e9 100644 --- a/community/WORKING-GROUPS.md +++ b/community/WORKING-GROUPS.md @@ -13,9 +13,10 @@ procedures. The working groups generate design docs which are kept in a [shared drive](https://drive.google.com/corp/drive/folders/0APnJ_hRs30R2Uk9PVA) and are available for anyone to read and comment on. The shared drive -currently grants edit and comment access to the -[knative-dev@](https://groups.google.com/forum/#!forum/knative-dev) -Google group. +currently grants read access to +[knative-users@](https://groups.google.com/forum/#!forum/knative-users) and edit +and comment access to the +[knative-dev@](https://groups.google.com/forum/#!forum/knative-dev) Google group. The current working groups are: