From 04bbfc4d86990dc66d38a293742c66204bd4a2e3 Mon Sep 17 00:00:00 2001 From: RichieEscarez Date: Thu, 30 Jan 2020 10:25:28 -0800 Subject: [PATCH] Fix links, titles, frontmatter, and use fully qualified knative/docs URLs (#45) * fix titles and links * add missing _index.md section file * add full repo url * add redirects to new URLs * typos * fix broken URLs from new /docs dir and add fully qualified URL to OWNERS * Update link text Co-authored-by: Ryan Gregg --- CODE-OF-CONDUCT.md | 2 ++ CONTRIBUTING.md | 2 ++ README.md | 4 ++-- REPOSITORY-GUIDELINES.md | 2 ++ REVIEWING.md | 2 ++ ROLES.md | 2 ++ SLACK-GUIDELINES.md | 2 ++ STEERING-COMMITTEE.md | 6 ++++-- TEAM-VALUES.md | 2 ++ TECH-OVERSIGHT-COMMITTEE.md | 2 ++ VALUES.md | 2 ++ WORKING-GROUPS.md | 2 ++ docs/DOCS-CONTRIBUTING.md | 32 ++++++++++++++++------------ docs/README.md | 4 ++-- docs/new-page-template.md | 6 +++--- mechanics/FEATURE-TRACKS.md | 29 +++++++++++++++---------- mechanics/README.md | 10 +-------- mechanics/WORKING-GROUP-PROCESSES.md | 2 ++ mechanics/_index.md | 10 +++++++++ 19 files changed, 80 insertions(+), 43 deletions(-) create mode 100755 mechanics/_index.md diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md index 3cdd794..ecc30f7 100644 --- a/CODE-OF-CONDUCT.md +++ b/CODE-OF-CONDUCT.md @@ -3,6 +3,8 @@ title: "Contributor covenant code of conduct" linkTitle: "Code of conduct" weight: 10 type: "docs" +aliases: + - /contributing/code-of-conduct/ --- ## Our Pledge diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3635f2..3c02992 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,8 @@ title: "Knative contributor guidelines" linkTitle: "Contributing to Knative" weight: 15 type: "docs" +aliases: + - /contributing/contributing/ --- So, you want to hack on Knative? Yay! diff --git a/README.md b/README.md index 2737b3a..3a87533 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Other Documents ## Introduction Knative is a Kubernetes-based platform to deploy and manage modern -serverless workloads. See [Knative docs](../docs/README.md) for in-depth +serverless workloads. See the [Knative documentation](https://github.com/knative/docs/tree/master/docs/README.md) for in-depth information about using Knative. ## Knative authors @@ -59,7 +59,7 @@ tools, platforms, languages, and products. By submitting a tutorial you can share your experience and help others who are solving similar problems. Community tutorials are stored in Markdown files under the `community` folder -[Community Samples](../community/samples/README.md). These documents are +[Community Samples](https://github.com/knative/docs/tree/master/community/samples/README.md). These documents are contributed, reviewed, and maintained by the community. Submit a Pull Request to the community sample directory under the Knative diff --git a/REPOSITORY-GUIDELINES.md b/REPOSITORY-GUIDELINES.md index 5740d0a..5803102 100644 --- a/REPOSITORY-GUIDELINES.md +++ b/REPOSITORY-GUIDELINES.md @@ -3,6 +3,8 @@ title: "Knative Repository Guidelines" linkTitle: "Repository Guidelines" weight: 25 type: "docs" +aliases: + - /contributing/repository-guidelines/ --- This document outlines a structure for creating and associating code diff --git a/REVIEWING.md b/REVIEWING.md index 4f04e92..aa85ad3 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -3,6 +3,8 @@ title: "Reviewing and merging Knative pull requests" linkTitle: "Pull request guidelines" weight: 60 type: "docs" +aliases: + - /contributing/reviewing/ --- As a community, we believe in the value of code reviews for all contributions. diff --git a/ROLES.md b/ROLES.md index 6f45176..b03f60d 100644 --- a/ROLES.md +++ b/ROLES.md @@ -3,6 +3,8 @@ title: "Knative community roles" linkTitle: "Community roles" weight: 55 type: "docs" +aliases: + - /contributing/roles/ --- This document describes the set of roles individuals might have within the diff --git a/SLACK-GUIDELINES.md b/SLACK-GUIDELINES.md index 7939dfe..4dc35df 100644 --- a/SLACK-GUIDELINES.md +++ b/SLACK-GUIDELINES.md @@ -3,6 +3,8 @@ title: "Slack guidelines" linkTitle: "Slack guidelines" weight: 45 type: "docs" +aliases: + - /contributing/slack-guidelines/ --- Slack is the main communication platform for Knative outside of our mailing diff --git a/STEERING-COMMITTEE.md b/STEERING-COMMITTEE.md index 208ec29..a61b49e 100644 --- a/STEERING-COMMITTEE.md +++ b/STEERING-COMMITTEE.md @@ -3,6 +3,8 @@ title: "Knative steering committee" linkTitle: "Steering committee" weight: 40 type: "docs" +aliases: + - /contributing/steering-committee/ --- The Knative Steering Committee (KSC) is the ultimate authority for the Knative @@ -65,8 +67,8 @@ between members, security reports, etc.) meetings are held in private. Meeting notes are available to members of the knative-dev mailing list (link to be added). -Questions and proposals for changes to governance are posted as issues in the -[docs repo](https://github.com/knative/docs), and the KSC invites your feedback +Questions and proposals for changes to governance are posted as +[issues in the docs repo](https://github.com/knative/docs/issues), and the KSC invites your feedback there. See [Getting in touch](#getting-in-touch) for other options. ## Committee members diff --git a/TEAM-VALUES.md b/TEAM-VALUES.md index 2ffad02..3d1c677 100644 --- a/TEAM-VALUES.md +++ b/TEAM-VALUES.md @@ -3,6 +3,8 @@ title: "Knative team values" linkTitle: "Team values" weight: 50 type: "docs" +aliases: + - /contributing/team-values/ --- We want to make sure every member has a shared understanding of the goals and diff --git a/TECH-OVERSIGHT-COMMITTEE.md b/TECH-OVERSIGHT-COMMITTEE.md index 40983e7..6915649 100644 --- a/TECH-OVERSIGHT-COMMITTEE.md +++ b/TECH-OVERSIGHT-COMMITTEE.md @@ -3,6 +3,8 @@ title: "Knative technical oversight committee" linkTitle: "Technical oversight committee" weight: 35 type: "docs" +aliases: + - /contributing/tech-oversight-committee/ --- The Knative Technical Oversight Committee (TOC) is responsible for cross-cutting diff --git a/VALUES.md b/VALUES.md index aa77e01..80f73c1 100644 --- a/VALUES.md +++ b/VALUES.md @@ -3,6 +3,8 @@ title: "Knative project values" linkTitle: "Project values" weight: 50 type: "docs" +aliases: + - /contributing/values/ --- # Knative Community Values diff --git a/WORKING-GROUPS.md b/WORKING-GROUPS.md index 3d0c3e6..f44de13 100644 --- a/WORKING-GROUPS.md +++ b/WORKING-GROUPS.md @@ -3,6 +3,8 @@ title: "Knative working group" linkTitle: "Join working groups" weight: 25 type: "docs" +aliases: + - /contributing/working-groups/ --- Most community activity is organized into _working groups_. diff --git a/docs/DOCS-CONTRIBUTING.md b/docs/DOCS-CONTRIBUTING.md index b12f189..2987332 100644 --- a/docs/DOCS-CONTRIBUTING.md +++ b/docs/DOCS-CONTRIBUTING.md @@ -2,6 +2,8 @@ title: "How to contribute" weight: 20 type: "docs" +aliases: + - /contributing/docs-contributing/ --- - [Before you begin](#before-you-begin) @@ -18,7 +20,7 @@ propose changes to this document in a pull request. ### Code of conduct -Knative follows the [Knative Code of Conduct](./CODE-OF-CONDUCT.md). By +Knative follows the [Knative Code of Conduct](../CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to knative-code-of-conduct@googlegroups.com. @@ -62,7 +64,7 @@ see a problem with the documentation, submit an issue using the following steps: When you create a bug report, include as many details as possible and include suggested fixes to the issue. If you know which Knative component your bug is related to, you can assign the appropriate - [Working Group Lead](./WORKING-GROUPS.md). + [Working Group Lead](../WORKING-GROUPS.md). - **Feature request**: For upcoming changes to the documentation or requests for more information on a particular subject. @@ -75,7 +77,7 @@ issue in the [`knative/website`repo](https://github.com/knative/website/issues). ### Working group -The [Knative Documentation Working Group](./WORKING-GROUPS.md#documentation) +The [Knative Documentation Working Group](../WORKING-GROUPS.md#documentation) meets weekly on Tuesdays and alternates between a 9am PT and a 4:30pm PT time to accommodate contributors in both the EMEA and APAC timezones. [Click here](https://calendar.google.com/calendar/embed?src=google.com_18un4fuh6rokqf8hmfftm5oqq4%40group.calendar.google.com) @@ -93,8 +95,8 @@ There are a couple different ways to jump in to the Knative doc set: in the backlog. - 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). + [install guides](https://github.com/knative/docs/tree/master/docs/install/README.md) and then try + [Getting Started with Knative Serving](https://github.com/knative/docs/tree/master/docs/install/getting-started-knative-app.md). You should keep a [friction log](https://devrel.net/developer-experience/an-introduction-to-friction-logging) @@ -263,17 +265,18 @@ in the product, or for a fix or update existing content. 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 + 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. + `release-0.5`. + Where `[COMMIT#]` is the commit of the PR that you merged in `master`. 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). +See a list of the available documentaion versions in the +[branches page](https://github.com/knative/docs/branches) +of the `knative/docs` repo. ## Assigning owners and reviewers @@ -287,7 +290,7 @@ 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. +[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` @@ -298,7 +301,7 @@ Because contributing to the documentation requires a different skill set than contributing to the Knative code base, we've defined the roles of documentation contributors separately from the roles of code contributors. -If you're looking for code contributor roles, see [ROLES](./ROLES.md). +If you're looking for code contributor roles, see [ROLES](../ROLES.md). ### Member @@ -355,7 +358,8 @@ Knative Steering committee to ask that you be added as a member of the Knative org. Once your sponsor notifies you that you've been added to the Knative org, open a -PR to add yourself as a docs-reviewer in the [OWNERS_ALIASES](../OWNERS_ALIASES) +PR to add yourself as a docs-reviewer in the +[OWNERS_ALIASES](https://github.com/knative/docs/tree/master/OWNERS_ALIASES) file. ## Approver @@ -411,4 +415,4 @@ to become an approver at a meeting of the Documentation Working Group. Once you feel you meet the criteria, you can ask one of the current approvers to nominate you to become an approver. If all existing approvers agree that you meet the criteria open a PR to add yourself as a docs-approver in the -[OWNERS_ALIASES](../OWNERS_ALIASES) file. +[OWNERS_ALIASES](https://github.com/knative/docs/tree/master/OWNERS_ALIASES) file. diff --git a/docs/README.md b/docs/README.md index 937a6ea..413a1b8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ We're excited that you're interested in contributing to the Knative documentatio ## Getting started -- [How to contribute](DOCS-CONTRIBUTING.md) -- Contains information about how to contribute and outlines the roles for Docs contributors. +- [How to contribute](./DOCS-CONTRIBUTING.md) -- Contains information about how to contribute and outlines the roles for Docs contributors. - [Template page](https://raw.githubusercontent.com/knative/community/master/docs/new-page-template.md) -- A blank documentation page that demonstrates how to format a new page and includes tips on structuring your documentation. @@ -11,4 +11,4 @@ We're excited that you're interested in contributing to the Knative documentatio - [#docs on the Knative Slack](https://slack.knative.dev) -- The #docs channel is the best place to go if you have questions about making changes to the documentation. We're happy to help! -- [Documentation working group](../WORKING-GROUPS.md#documentation) -- Come join us in the working group to meet other docs contributors and ask any questions you might have. \ No newline at end of file +- [Documentation working group](../WORKING-GROUPS.md#documentation) -- Come join us in the working group to meet other docs contributors and ask any questions you might have. diff --git a/docs/new-page-template.md b/docs/new-page-template.md index f8edeb8..f309d0b 100644 --- a/docs/new-page-template.md +++ b/docs/new-page-template.md @@ -1,9 +1,9 @@ --- # This section is called the "frontmatter" for your page title: "Title for your page" # Use sentence case for titles -#linkTitle: "Link for this page in the sidebar" +linkTitle: "Template: New docs page" # The linkTitle field (above) is optional; use it to provide a shorter link if your page title is very long -weight: 10 # This affects the placement of the link in the sidebar on the left. Pages are ordered from top to bottom by weight, lowest to highest. +weight: 50 # This affects the placement of the link in the sidebar on the left. Pages are ordered from top to bottom by weight, lowest to highest. type: "docs" # You won't need to update this. #aliases: # - /docs/example/redirect/moved-renamed-page @@ -43,7 +43,7 @@ Avoid nesting headings directly on top of each other with no text inbetween. Avoid nesting headings directly on top of each other with no text inbetween. -Put code into a code block. +Put code into a code block. 1. Here's a code snippet: diff --git a/mechanics/FEATURE-TRACKS.md b/mechanics/FEATURE-TRACKS.md index 80662cb..f396b00 100644 --- a/mechanics/FEATURE-TRACKS.md +++ b/mechanics/FEATURE-TRACKS.md @@ -1,4 +1,11 @@ -# Knative Feature Tracks +--- +title: "Knative feature tracks" +linkTitle: "Feature tracks" +weight: 40 +type: "docs" +aliases: + - /contributing/mechanics/feature-tracks/ +--- This document outlines the Knative process for adding non-trivial features. The intent of this process is to articulate the best practices many successful @@ -87,17 +94,17 @@ guide); by default a majority of the WG leads shall decide. The outcome of a review may not be an immediate decision, and the contributor may get sent back to gather more information and iterate. -When a proposal is accepted, the leads should designate one or more -reviewers[3.1](#3.1) within the WG as "sponsors" for the -feature to help shepherd it through the process. It is recommended that at -least one sponsor be an approver -([e.g.](https://github.com/knative/serving/blob/2018fcd98c18922cb1ce8b0207aa9aa6bef5eed1/OWNERS_ALIASES#L19)), -but if non-approvers -([e.g.](https://github.com/knative/serving/blob/2018fcd98c18922cb1ce8b0207aa9aa6bef5eed1/OWNERS_ALIASES#L25)) -are listed, they should be considered the primary reviewer(s) so that they can -hone their review skills and work towards approver. +When a proposal is accepted, the leads should designate one or more +reviewers[3.1](#3.1) within the WG as "sponsors" for the +feature to help shepherd it through the process. It is recommended that at +least one sponsor be an "approver" (someone listed under an +[`*-approvers`](https://github.com/knative/serving/blob/master/OWNERS_ALIASES) list). +If that sponsor is not an approver (for example, someone listed under an +[`*-reviewers`](https://github.com/knative/serving/blob/master/OWNERS_ALIASES) list), +they should initially become the primary reviewer(s) so that they can hone their review skills +and work towards the approver role. -> 3.1 - Leads should try to be sensitive to the relative timezone of contributors with their sponsors to reduce cycle times on reviews. +> 3.1 - Leads should try to be sensitive to the relative timezone of contributors with their sponsors to reduce cycle times on reviews. ## Step 4: The Breakdown diff --git a/mechanics/README.md b/mechanics/README.md index fd97ad9..919b1a5 100644 --- a/mechanics/README.md +++ b/mechanics/README.md @@ -1,11 +1,3 @@ ---- -title: "Knative processes and guidelines" -linkTitle: "Knative processes" -weight: 20 -type: "docs" ---- - -# Knative processes This directory provides a location for documenting and recording common Knative community practices. At the moment, these practices (except for the formation of @@ -22,4 +14,4 @@ processes; either in their own repo or in a pointer to these docs. - Experimental features - Alpha/beta/GA maturity ---> \ No newline at end of file +--> diff --git a/mechanics/WORKING-GROUP-PROCESSES.md b/mechanics/WORKING-GROUP-PROCESSES.md index 986bb8d..9e54e68 100644 --- a/mechanics/WORKING-GROUP-PROCESSES.md +++ b/mechanics/WORKING-GROUP-PROCESSES.md @@ -3,6 +3,8 @@ title: "Knative working group processes and guidelines" linkTitle: "Working group guidelines" weight: 30 type: "docs" +aliases: + - /contributing/mechanics/working-group-processes/ --- This document describes the processes we use to manage the Knative working diff --git a/mechanics/_index.md b/mechanics/_index.md new file mode 100755 index 0000000..e79e051 --- /dev/null +++ b/mechanics/_index.md @@ -0,0 +1,10 @@ +--- +title: "Knative processes and guidelines" +linkTitle: "Processes and guidelines" +weight: 20 +type: "docs" +aliases: + - /contributing/mechanics/ +--- + +{{% readfile file="README.md" %}}