[WIP] Clean up contribution docs #5307
Conversation
knative-prow
bot
added
the
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: abrennan89 The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
knative-prow
bot
added
approved
✅ Deploy Preview for knative ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site settings. |
abrennan89
force-pushed
the
contribDocs
branch
from
7d99cd7 to
276d0af
Compare
|
One of the things that came up in the project meeting yesterday was that having things like the calendar / learn and connect section / community meet-up in a "Contributing" section might inadvertently hide them from new end users who want to get involved but aren't necessarily looking to contribute. One idea was maybe renaming this section "Community", though given the work you've done here, maybe it would make more sense to make a separate section... (?) |
There was a problem hiding this comment.
Thanks @abrennan89 - looks like some really nice improvements. A few minor suggestions.
|
|
||
| Knative components offer developers Kubernetes-native APIs for deploying | ||
| serverless-style functions, applications, and containers to an auto-scaling | ||
| runtime. |
There was a problem hiding this comment.
It might be good to note eventing components here as well. Maybe something like this?
| runtime. | |
| runtime. Knative applications work equally well with both HTTP and CloudEvents workloads, with a robust catalog of project and community provided event sources. |
There was a problem hiding this comment.
This content feels like it should move up to the main / marketing page, rather than moving down into "contributing" -- I did copy over the front & center of the different audiences, but it seems like our public answer for "what is Knative and what is it for" should align with our community / contributor answer to the same.
That means I didn't merge in the "what Knative components offer" here, nor the "Knative components are intended to be integrated into ..." (I'm not sure I agree with the latter take, though I think Knative is a good component to integrate into those platforms).
| operate. | ||
|
|
||
| Any enterprise or cloud provider can adopt Knative components into their own | ||
| systems and pass the benefits along to their customers. |
There was a problem hiding this comment.
| systems and pass the benefits along to their customers. | |
| systems and pass the benefits along to their developers, platform teams, and customers. |
There was a problem hiding this comment.
Added a link to ADOPTERS.MD here to highlight people who have adopted the project.
|
|
||
| ## More ways to get involved | ||
|
|
||
| Even if there’s not an issue opened for it, we can always use more testing throughout the platform. Similarly, we can always use more docs, richer docs, insightful docs. Or maybe a cool blog post? And if you’re a web developer, we could use your help in spiffing up our public-facing web site. |
There was a problem hiding this comment.
Moved this to contributing.md, but put some of the flavor into the definition of "contributor" at the start of the README.md.
|
|
||
| Even if there’s not an issue opened for it, we can always use more testing throughout the platform. Similarly, we can always use more docs, richer docs, insightful docs. Or maybe a cool blog post? And if you’re a web developer, we could use your help in spiffing up our public-facing web site. | ||
|
|
||
| [Bug reports](https://github.com/knative/serving/issues/new) and friction logs |
There was a problem hiding this comment.
It's odd to have only a link to serving issues here. I'm not sure what the best approach might be here. It probably doesn't make sense either to have a list of repos with links to their issues. Something to give thought to, I suppose.
There was a problem hiding this comment.
I added a section for "Bug Reports and Feature Requests" in #5348 , preferring that content
|
|
||
| ## Getting started | ||
|
|
||
| Before you can make a contribution to Knative, you must sign the CNCF [EasyCLA](https://easycla.lfx.linuxfoundation.org/) using the same email address you used to register for Github. |
There was a problem hiding this comment.
| Before you can make a contribution to Knative, you must sign the CNCF [EasyCLA](https://easycla.lfx.linuxfoundation.org/) using the same email address you used to register for Github. | |
| Before you can make a contribution to Knative, you must sign the CNCF Contributor License Agreement, [EasyCLA](https://easycla.lfx.linuxfoundation.org/) using the same email address you use on Github. |
It might be good to spell out what CLA stands for.
The Github change is because what you really need is the email address used when doing git commit on your code contributions. This typically aligns with an email address used on GitHub but may not align with the one used when registering for an account.
There was a problem hiding this comment.
Added this into the section in contributing.md covering the CLA. Since not everyone participating in the community is necessarily making code contributions, I reverted the move of the CLA documentation into the main README.
| the goals and values we hold as a team. | ||
|
|
||
| Knative has public and recorded monthly community meetings. | ||
| Each project has one or more working groups driving the project, and Knative has |
There was a problem hiding this comment.
| Each project has one or more working groups driving the project, and Knative has | |
| Each component has one or more working groups driving the effort, and Knative has |
There was a problem hiding this comment.
(Fixed this wording in governance.md, which was originally in about.md)
There was a problem hiding this comment.
Merged 276d0af into #5348, responded to the comments here and left a few of my own about how I handled the merge conflict.
|
|
||
| Knative components offer developers Kubernetes-native APIs for deploying | ||
| serverless-style functions, applications, and containers to an auto-scaling | ||
| runtime. |
There was a problem hiding this comment.
This content feels like it should move up to the main / marketing page, rather than moving down into "contributing" -- I did copy over the front & center of the different audiences, but it seems like our public answer for "what is Knative and what is it for" should align with our community / contributor answer to the same.
That means I didn't merge in the "what Knative components offer" here, nor the "Knative components are intended to be integrated into ..." (I'm not sure I agree with the latter take, though I think Knative is a good component to integrate into those platforms).
| operate. | ||
|
|
||
| Any enterprise or cloud provider can adopt Knative components into their own | ||
| systems and pass the benefits along to their customers. |
There was a problem hiding this comment.
Added a link to ADOPTERS.MD here to highlight people who have adopted the project.
|
|
||
| Even if there’s not an issue opened for it, we can always use more testing throughout the platform. Similarly, we can always use more docs, richer docs, insightful docs. Or maybe a cool blog post? And if you’re a web developer, we could use your help in spiffing up our public-facing web site. | ||
|
|
||
| [Bug reports](https://github.com/knative/serving/issues/new) and friction logs |
There was a problem hiding this comment.
I added a section for "Bug Reports and Feature Requests" in #5348 , preferring that content
|
|
||
| ## More ways to get involved | ||
|
|
||
| Even if there’s not an issue opened for it, we can always use more testing throughout the platform. Similarly, we can always use more docs, richer docs, insightful docs. Or maybe a cool blog post? And if you’re a web developer, we could use your help in spiffing up our public-facing web site. |
There was a problem hiding this comment.
Moved this to contributing.md, but put some of the flavor into the definition of "contributor" at the start of the README.md.
|
|
||
| ## Getting started | ||
|
|
||
| Before you can make a contribution to Knative, you must sign the CNCF [EasyCLA](https://easycla.lfx.linuxfoundation.org/) using the same email address you used to register for Github. |
There was a problem hiding this comment.
Added this into the section in contributing.md covering the CLA. Since not everyone participating in the community is necessarily making code contributions, I reverted the move of the CLA documentation into the main README.
|
|
||
| Read the [Code of conduct](https://github.com/knative/community/blob/main/CODE-OF-CONDUCT.md). | ||
|
|
||
| ## Governance |
There was a problem hiding this comment.
Since governance is basically a giant link farm that's mostly of interest to people who want to know the nitty-gritty of how the project operates, I moved it from about.md to governance.md, but kept it as a separate document.
| the goals and values we hold as a team. | ||
|
|
||
| Knative has public and recorded monthly community meetings. | ||
| Each project has one or more working groups driving the project, and Knative has |
There was a problem hiding this comment.
(Fixed this wording in governance.md, which was originally in about.md)
|
/assign @nainaz |
|
#5348 superseded this one, right? |
|
lol, oops. I had the wrong window open! /unassign nainaz |
|
The changes here were pulled into #5348 , so going to close this to prevent duplication |
Reviewing and editing contributor docs to make them more user friendly.
Related to #4558 - the docs style guide, contrib guidelines etc I think are too hard to find, so folks are ignoring them, and our doc reviews take much longer as a result.
Preview links: