Skip to content

Commit

Permalink
Update docs contributor guidelines (#1193)
Browse files Browse the repository at this point in the history 
* assigning PRs and choosing branches

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* add missing link to slack

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* clarify commit #

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* add missing link to community samples

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* add link to Owners files that lists TWs

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* Update contributing/DOCS-CONTRIBUTING.md

Co-Authored-By: RichieEscarez <[email protected]>

* consistent variables

* remove duplicate statement

* revise wording

* add link, fix typos, and revise for clarity

* clarify owner vs reviewer and add prow links/commands
  • Loading branch information
@RichieEscarez @knative-prow-robot
RichieEscarez authored and knative-prow-robot committed Apr 19, 2019
1 parent e0ebe6d commit 39e9017
Show file tree
Hide file tree
Showing 2 changed files with 200 additions and 33 deletions.
232 changes: 199 additions & 33 deletions contributing/DOCS-CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,10 @@ see a problem with the documentation, submit an issue using the following steps:

Note that code issues should be filed against the
[individual Knative repositories](http://github.com/knative), while
documentation issues should go in the `docs` repository.
documentation issues should go in the
[`knative/docs`repo](https://github.com/knative/docs/issues). If the issue is
specific to the [https://knative.dev](https://knative.dev) website, open the issue
in the [`knative/website`repo](https://github.com/knative/website/issues).

### Working group

Expand All @@ -68,45 +71,208 @@ documentation efforts, who are happy to help you get started.

There are a couple different ways to jump in to the Knative doc set:

- Look at issues in the Docs repo labled
[Good First Issue](https://github.com/knative/docs/labels/kind%2Fgood-first-issue).
- Run through the [install guide](../install/README.md) for the platform of your
choice, as well as the
[Getting Started with Knative App Deployment](../install/getting-started-knative-app.md)
guide, and keep a
[friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging)
of the experience. What was hard for you? Then open a PR with a few
improvements you could make from the friction log you kept. How can you make
the documentation better so that others don't run into the same issues you
did?
- Look for a
[Good First Issue](https://github.com/knative/docs/labels/kind%2Fgood-first-issue)
in the backlog.

### Submitting documentation PRs - what to expect
- Try out Knative and send us feedback. For example, run through one of the
[install guides](../install/README.md) and then try
[Getting Started with Knative Serving](../install/getting-started-knative-app.md).

You should keep a
[friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging)
of your experience and then use that to open your first set of PRs.
Examples:

- What was hard for you?
- Did you stumble on something because it wasn't clear?
- Was a dependency not mentioned?

**A few pointers and other considerations**

- Think about how you can improve the documentation as a whole. <br>
For example, how can you fix the issue you found so that others don't run
into the same challenges?

Here's what will happen after you open a PR in the Docs repo:
- Are there multiple places that could be fixed?

1. One of the Docs approvers will triage the PR and provide an initial
documentation review as soon as possible.
1. If the PR involves significant changes or additions to sample code, we'll
flag it for engineer review.
1. Once we're satisfied with the quality of the writing and the accuracy of the
content, we'll approve the change.
- Are there other pages that you should apply your update?

- Would it help if there was a link to more or related information on a
the page? On a related page?

- Was the title or description misleading? Did you expect to find something
else?

- If you find something and don't have the bandwidth to open a PR,
make us aware of the pain point and open an
[Issue](https://github.com/knative/docs/issues/new).

### Submitting documentation PRs - what to expect

If you're making a change to the documentation, you should submit a PR against
the master branch.
Here's what generally happens when you open a PR against the `knative/docs` repo:

1. One of the assigned repo maintainers will triage the PR by assigning relative
priority, adding appropriate labels, and performing an initial documentation
review.
1. If the PR involves significant technical changes, for example new features,
or new and changed sample code, the PR is assigned to a Subject Matter
Expert (SME), typically an engineer working on Knative, for technical review and approval.
1. When both the technical writers and SMEs are satisfied with the quality
of the writing and the technical accuracy of the content, the PR can be
merged. A PR requires two labels before it can merge:
`lgtm` and `approved`.
* The SME is responsible for reviewing the technical accuracy and adding
the `lgtm` label.

* The [Knative technical writers](https://github.com/knative/docs/blob/master/OWNERS_ALIASES)
generally use the publicly available
[Google Style Guide](https://developers.google.com/style/) for writing standards,
and are who provide the `approved` label when the content meets quality, clarity, and
organization standards.

We appreciate contributions to the docs, so if you open a PR we
will help you get it merged. You can also post in the `#docs`
[Slack channel](https://knative.slack.com/) to get input on your ideas before creating a PR.

### Putting your docs in the right place

Knative uses the [docs repository](https://github.com/knative/docs) for all
general documentation for Knative components. However, formal specifications or
documentation most relevant to contributors of a component should be placed in
the `docs` folder in a given component's repository. An example of this is the
[spec](https://github.com/knative/serving/tree/master/docs/spec) folder in the
Serving component.

Code samples follow a similar strategy, where most code samples should be
located in the `docs` repository. If there are code samples used for testing
that are only expected to be used by contributors, those samples are put in the
`samples` folder within the component repo.
There are currently two general types of Knative docs, either contributor
related content, or external-facing user content.

#### Choosing the correct repo

Depending on the type of content that you want to contribute, it might belong in
one of the Knative code repositories (`knative/serving`, `knative/eventing`,
etc.) or in `knative/docs`, the Knative documentation repo.

* **Contributor-focused content**

* *Documentation*: Includes content that is component specific and relevant
only to contributors of a given component. Contributor focused
documentation is located in the corresponding `docs` folder of that
component's repository. For example, if you contribute code to
the Knative Serving component, you might need to add contributor focused
information into the `docs` folder of the
[knative/serving repo](https://github.com/knative/serving/tree/master/docs/).

* *Code samples*: Includes contributor related code or samples. Code or samples
that are contributor focused also belong in their corresponding
component's repo. For example, Eventing specific test code is located in the
[knative/eventing tests](https://github.com/knative/eventing/tree/master/test)
folder.

* **User-focused content**

* *Documentation*: Includes all content for Knative users. The
external-facing user documentation belongs in the
[`knative/docs` repo](https://github.com/knative/docs). All content in
`knative/docs` is published to [https://knative.dev](https://knative.dev).

* *Code samples*: Includes user-facing code samples and their accompanying
step-by-step instructions. User code samples are currently separated into
two different locations within the `knative/docs` repo. See the following
section for details about determining where you can add your code sample.

##### Determining where to add user focused code samples

There are currently two categories of user-focused code samples,
*Knative owned and maintained* and *Community owned and maintained*.

* **Knative owned and maintained**: Includes code samples that are actively
maintained and e2e tested. To ensure content currency and balance available
resource, only the code samples that meet the following requirements are
located in the `docs/[*component*]/samples` folders of the `knative/docs` repo:

* *Actively maintained* - The code sample has an active Knative team member
who has committed to regular maintenance of that content and ensures that
the code is updated and working for every product release.
* *Receives regular traffic* - To avoid hosting and maintaining unused
or stale content, if code samples are not being viewed and fail to
receive attention or use, those samples will be moved into the
"[community maintained](https://github.com/knative/docs/tree/master/community/samples)"
set of samples.
* *Passes e2e testing* - All code samples within `docs/[*component*]/samples`
folders must align with (and pass) the
[`e2e` tests](https://github.com/knative/docs/tree/master/test).

Depending on the Knative component covered by the code sample that you
want to contribute, your PR should add that sample in one of the following
folders:

* Build samples: [`/docs/build/samples`](https://github.com/knative/docs/tree/master/docs/build/samples)
* Eventing samples: [`/docs/eventing/samples`](https://github.com/knative/docs/tree/master/docs/eventing/samples)
* Serving samples: [`/docs/serving/samples`](https://github.com/knative/docs/tree/master/docs/serving/samples)

* **Community owned and maintained samples**: Code samples that have
been contributed by Knative community members. These samples might not receive
regular maintenance. It is possible that a sample is no longer current and
is not actively maintained by its original author. While we encourage a
contributor to maintain their content, we acknowledge that it's not always
possible for certain reasons, for example other commitments and time
constraints.

While a sample might be out of date, it could still provide assistance and
help you get up-and-running with certain use-cases. If you find that
something is not right or contains outdated info, open an
[Issue](https://github.com/knative/docs/issues/new). The sample might be
fixed if bandwidth or available resource exists, or the sample might be
taken down and archived into the last release branch where it worked.

#### Choosing the correct branch

It is likely that your docs contribution is either for new or changed
features in the product, or for a fix or update existing content.

* **New or changed features**:
If you are adding or updating documentation for a new or changed feature,
you likely want to open your PR against the `master` branch. All pre-release
content for active Knative development belongs in
[`master`](https://github.com/knative/docs/tree/master/).

* **Fixes and updates**:
If you find an issue in a past release, for example a typo or out-of-date
content, you likely need to open multiple and subsequent PRs. If not a
followup PR, at least add the "`cherrypick` labels" to your original PR
to indicate in which of the past release that your change affects.

For example, if you find a typo in a page of the `v0.5` release, then that
page in the `master` branch likely also has that typo.

To fix the typo:
1. Open a PR against the
[`master`](https://github.com/knative/docs/tree/master/) branch.
1. Add one or more `cherrypick-#.#` labels to that PR to indicate which
of the past release branches should also be fixed. Generally, we only maintain the most recent numbered release.
1. If you want to complete the fix yourself (best practice), you then open
a subsequent PR by running `git cherry-pick [COMMIT#]` against
the [release-0.5](https://github.com/knative/docs/tree/release-0.5).
Where [COMMIT#] is the commit of your merged PR.

Note: Depending on workload and available bandwidth, one of
the Knative team members might be able to help handle the
`git cherry-pick` in order to push the fix into the affected release
branch(es).

For a list of the available branches in the `knative/docs` repo, see
[Documentation Releases](https://github.com/knative/docs/blob/master/doc-releases.md).

## Assigning owners and reviewers

For both documentation and code samples, you should assign your PR to a single
owner ("*Assignee*"). It's best to set the "Assignee" and include other stakeholders
as "Reviewers" rather than leaving it unassigned or allowing
[Prow](https://prow.k8s.io/command-help) to auto assign reviewers.

Use the `/assign` command to set the owner. For example: `/assign @owner_id`

For code samples, initially set the owner of your PR to the SME who should review
for technical accuracy. If you don't know who the appropriate owner is, nor
who your reviewers should be for your PR, you can assign the
[current working group lead](./WORKING-GROUPS.md) of the related component.

If you want to notify and include other stakeholders in your PR review, use the
`/cc` command. For example: `/cc @stakeholder_id1 @stakeholder_id2`

## Docs contributor roles

Expand Down
1 change: 1 addition & 0 deletions doc-releases.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ files in the following branches:

The following branches include content for released versions of Knative:

- [**`release-0.5`**](https://github.com/knative/docs/tree/release-0.5)
- [**`release-0.4`**](https://github.com/knative/docs/tree/release-0.4)
- [**`release-0.3`**](https://github.com/knative/docs/tree/release-0.3)
- [**`release-0.2`**](https://github.com/knative/docs/tree/release-0.2)
Expand Down

0 comments on commit 39e9017

Please sign in to comment.