*: Assorted internal-reference cleanups

This is mostly replacing
https://github.com/kubernetes/community/blob/master/... links with
relative links, because relative links are easier to maintain.  For
example, if you rename a.md to b.md in a feature branch, updating an
/a.md to /b.md target will work immediately (e.g. during pull-request
review), while updating
https://github.com/kubernetes/community/blob/master/a.md to
https://github.com/kubernetes/community/blob/master/b.md will only
work after your branch lands the rename in master.

I'm not sure why the #L1454 fragment was part of the old
sig-governance template sigs.yaml link, but it's been there since the
template landed in 68658bf (Provide short template for SIG
governance, 2018-02-23, #1830).  I've removed it in this commit.

The Kubernetes Charter README link in the sig-governance template
could just be:

  [Kubernetes Charter README]: README.md

but I've based it on the project root and back to make life easier
on new SIGs which copy/paste the file to a new location in this
repository.

I personally prefer targets that use ../ for referencing other
directories within a project, because those also work with generic
Markdown tools (e.g. Emacs' Markdown mode).  I've gone with /-rooted
targets in this commit as requested in
/sig-contributor-experience/markdown-link-style-guide.md.

I've also chased a few files and anchors as they've moved around,
e.g. the OBSOLETE_templates.md rename from 18958f8 (addressing Brians
comments, 2017-09-06, #1010) and the "and maintenance" header addition
from f471f6b (Add new contact info for Paris and me, 2017-10-17,

This commit isn't complete, but it's a step in the right direction and
all I had time for tonight ;).

committee-steering/governance/README.md

@@ -71,5 +71,5 @@ See [frequently asked questions]
 [Recommendations and requirements]: sig-governance-requirements.md
 [Short Template]: sig-governance-template-short.md
 [frequently asked questions]: FAQ.md
-[sigs.yaml]: https://github.com/kubernetes/community/blob/master/sigs.yaml
-[sig-architecture example]: ../../sig-architecture/charter.md
+[sigs.yaml]: /sigs.yaml
+[sig-architecture example]: /sig-architecture/charter.md

committee-steering/governance/sig-governance-template-short.md

@@ -132,7 +132,7 @@ Issues impacting multiple subprojects in the SIG should be resolved by either:
 
 [lazy-consensus]: http://communitymgt.wikia.com/wiki/Lazy_consensus
 [super-majority]: https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote
-[KEP]: https://github.com/kubernetes/community/blob/master/keps/0000-kep-template.md
-[sigs.yaml]: https://github.com/kubernetes/community/blob/master/sigs.yaml#L1454
-[OWNERS]: contributors/devel/owners.md
-[Kubernetes Charter README]: https://github.com/kubernetes/community/blob/master/committee-steering/governance/README.md
+[KEP]: /keps/0000-kep-template.md
+[sigs.yaml]: /sigs.yaml
+[OWNERS]: /contributors/guide/owners.md
+[Kubernetes Charter README]: /committee-steering/governance/README.md

communication/README.md

@@ -88,8 +88,6 @@ Kubernetes is the main focus of CloudNativeCon/KubeCon, held every spring in Eur
 [Blog]: http://blog.kubernetes.io
 [calendar.google.com]: https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles
 [CNCF code of conduct]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
-[communication]: /communication.md
-[community meeting]: /communication.md#weekly-meeting
 [events]: https://www.cncf.io/events/
 [file an issue]: https://github.com/kubernetes/kubernetes/issues/new
 [Google+]: https://plus.google.com/u/0/b/116512812300813784482/116512812300813784482

communication/zoom-guidelines.md

@@ -1,7 +1,7 @@
 # Zoom Guidelines
 
 Zoom is the main video communication platform for Kubernetes. 
-It is used for running the [community meeting](https://github.com/kubernetes/community/blob/master/events/community-meeting.md) and SIG meetings. 
+It is used for running the [community meeting](/events/community-meeting.md) and SIG meetings.
 Since the Zoom meetings are open to the general public, a Zoom host has to moderate a meeting if a person is in violation of the code of conduct. 
 
 These guidelines are meant as a tool to help Kubernetes members manage their Zoom resources. 
@@ -36,7 +36,7 @@ Contact [SIG Contributor Experience](https://github.com/kubernetes/community/tre
 - @castrojo
 
 Each SIG should have at least one person with a paid Zoom account. 
-See the [SIG Creation procedure](https://github.com/kubernetes/community/blob/master/sig-governance.md#sig-creation-procedure) document on how to set up an initial account. 
+See the [SIG Creation procedure](/sig-governance.md#sig-creation-and-maintenance-procedure) document on how to set up an initial account.
 
 The Zoom licenses are managed by the [CNCF Service Desk](https://github.com/cncf/servicedesk). 
 

contributors/design-proposals/architecture/declarative-application-management.md

@@ -6,7 +6,7 @@ Most users will deploy a combination of applications they build themselves, also
 
 In the case of the latter, users sometimes have the choice of using hosted SaaS products that are entirely managed by the service provider and are therefore opaque, also known as **_blackbox_** *services*. However, they often run open-source components themselves, and must configure, deploy, scale, secure, monitor, update, and otherwise manage the lifecycles of these **_whitebox_** *COTS applications*.
 
-This document proposes a unified method of managing both bespoke and off-the-shelf applications declaratively using the same tools and application operator workflow, while leveraging developer-friendly CLIs and UIs, streamlining common tasks, and avoiding common pitfalls. The approach is based on observations of several dozen configuration projects and hundreds of configured applications within Google and in the Kubernetes ecosystem, as well as quantitative analysis of Borg configurations and work on the Kubernetes [system architecture](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture.md), [API](https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md), and command-line tool ([kubectl](https://github.com/kubernetes/community/wiki/Roadmap:-kubectl)).
+This document proposes a unified method of managing both bespoke and off-the-shelf applications declaratively using the same tools and application operator workflow, while leveraging developer-friendly CLIs and UIs, streamlining common tasks, and avoiding common pitfalls. The approach is based on observations of several dozen configuration projects and hundreds of configured applications within Google and in the Kubernetes ecosystem, as well as quantitative analysis of Borg configurations and work on the Kubernetes [system architecture](architecture.md), [API](/contributors/devel/api-conventions.md), and command-line tool ([kubectl](https://github.com/kubernetes/community/wiki/Roadmap:-kubectl)).
 
 The central idea is that a toolbox of composable configuration tools should manipulate configuration data in the form of declarative API resource specifications, which serve as a [declarative data model](https://docs.google.com/document/d/1RmHXdLhNbyOWPW_AtnnowaRfGejw-qlKQIuLKQWlwzs/edit#), not express configuration as code or some other representation that is restrictive, non-standard, and/or difficult to manipulate.
 
@@ -208,7 +208,7 @@ In case it’s not clear from the above, I do not consider configuration schemas
 
 Given the pitfalls of parameterization and configuration DSLs, as mentioned at the beginning of this document, configuration tooling should manipulate configuration **data**, not convert configuration to code nor other marked-up syntax, and, in the case of Kubernetes, this data should primarily contain specifications of the **literal Kubernetes API resources** required to deploy the application in the manner desired by the user. The Kubernetes API and CLI (kubectl) were designed to support this model, and our documentation and examples use this approach.
 
-[Kubernetes’s API](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture.md#cluster-control-plane-aka-master) provides IaaS-like container-centric primitives such as Pods, Services, and Ingress, and also lifecycle controllers to support orchestration (self-healing, scaling, updates, termination) of common types of workloads, such as ReplicaSet (simple fungible/stateless app manager), Deployment (orchestrates updates of stateless apps), Job (batch), CronJob (cron), DaemonSet (cluster services), StatefulSet (stateful apps), and [custom third-party controllers/operators](https://coreos.com/blog/introducing-operators.html). The workload controllers, such as Deployment, support declarative upgrades using production-grade strategies such as rolling update, so that the client doesn’t need to perform complex orchestration in the common case. (And we’re moving [proven kubectl features to controllers](https://github.com/kubernetes/kubernetes/issues/12143), generally.) We also deliberately decoupled service naming/discovery and load balancing from application implementation in order to maximize deployment flexibility, which should be preserved by the configuration mechanism.
+[Kubernetes’s API](architecture.md#cluster-control-plane-aka-master) provides IaaS-like container-centric primitives such as Pods, Services, and Ingress, and also lifecycle controllers to support orchestration (self-healing, scaling, updates, termination) of common types of workloads, such as ReplicaSet (simple fungible/stateless app manager), Deployment (orchestrates updates of stateless apps), Job (batch), CronJob (cron), DaemonSet (cluster services), StatefulSet (stateful apps), and [custom third-party controllers/operators](https://coreos.com/blog/introducing-operators.html). The workload controllers, such as Deployment, support declarative upgrades using production-grade strategies such as rolling update, so that the client doesn’t need to perform complex orchestration in the common case. (And we’re moving [proven kubectl features to controllers](https://github.com/kubernetes/kubernetes/issues/12143), generally.) We also deliberately decoupled service naming/discovery and load balancing from application implementation in order to maximize deployment flexibility, which should be preserved by the configuration mechanism.
 
 [Kubectl apply](https://github.com/kubernetes/kubernetes/issues/15894)  [was designed](https://github.com/kubernetes/kubernetes/issues/1702) ([original proposal](https://github.com/kubernetes/kubernetes/issues/1178)) to support declarative updates without clobbering operationally and/or automatically set desired state. Properties not explicitly specified by the user are free to be changed by automated and other out-of-band mechanisms. Apply is implemented as a 3-way merge of the user’s previous configuration, the new configuration, and the live state.
 
@@ -252,7 +252,7 @@ Deployment of bespoke applications involves multiple steps:
 
 Step 1, building the image, is out of scope for Kubernetes. Step 3 is covered by kubectl apply. Some tools in the ecosystem, such as [Draft](https://github.com/Azure/draft), combine the 3 steps.
 
-Kubectl contains ["generator" commands](https://github.com/kubernetes/community/blob/master/contributors/devel/kubectl-conventions.md#generators), such as [kubectl run](https://kubernetes.io/docs/user-guide/kubectl/v1.7/#run), expose, various create commands, to create commonly needed Kubernetes resource configurations. However, they also don’t help users understand current best practices and conventions, such as proper label and annotation usage. This is partly a matter of updating them and partly one of making the generated resources suitable for consumption by new users. Options supporting declarative output, such as dry run, local, export, etc., don’t currently produce clean, readable, reusable resource specifications ([example](https://blog.heptio.com/using-kubectl-to-jumpstart-a-yaml-file-heptioprotip-6f5b8a63a3ea))**.** We should clean them up.
+Kubectl contains ["generator" commands](/contributors/devel/kubectl-conventions.md#generators), such as [kubectl run](https://kubernetes.io/docs/user-guide/kubectl/v1.7/#run), expose, various create commands, to create commonly needed Kubernetes resource configurations. However, they also don’t help users understand current best practices and conventions, such as proper label and annotation usage. This is partly a matter of updating them and partly one of making the generated resources suitable for consumption by new users. Options supporting declarative output, such as dry run, local, export, etc., don’t currently produce clean, readable, reusable resource specifications ([example](https://blog.heptio.com/using-kubectl-to-jumpstart-a-yaml-file-heptioprotip-6f5b8a63a3ea))**.** We should clean them up.
 
 Openshift provides a tool, [oc new-app](https://docs.openshift.com/enterprise/3.1/dev_guide/new_app.html), that can pull source-code templates, [detect](https://github.com/kubernetes/kubernetes/issues/14801)[ application types](https://github.com/kubernetes/kubernetes/issues/14801) and create Kubernetes resources for applications from source and from container images. [podex](https://github.com/kubernetes/contrib/tree/master/podex) was built to extract basic information from an image to facilitate creation of default Kubernetes resources, but hasn’t been kept up to date. Similar resource generation tools would be useful for getting started, and even just [validating that the image really exists](https://github.com/kubernetes/kubernetes/issues/12428) would reduce user error.
 
@@ -322,13 +322,13 @@ Benefits of these approaches:
 
 An area where more investigation is needed is explicit inline parameter substitution, which, while overused and should be rendered unnecessary by the capabilities described above, is [frequently requested](https://stackoverflow.com/questions/44832085/passing-variables-to-args-field-in-a-yaml-file-kubernetes) and has been reinvented many times by the community.
 
-A [simple parameterization approach derived from Openshift’s design](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/templates.md) was approved because it was constrained in functionality and solved other problems (e.g., instantiation of resource variants by other controllers, [project templates in Openshift](https://github.com/openshift/training/blob/master/content/default-project-template.yaml)). That proposal explains some of the reasoning behind the design tradeoffs, as well as the [use cases](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/templates.md#use-cases). Work started, but was abandoned, though there is an independent [client-based implementation](https://github.com/InQuicker/ktmpl). However, the Template resource wrapped the resource specifications in another object, which is suboptimal, since transformations would then need to be able to deal with standalone resources, Lists of resources, and Templates, or would need to be applied post-instantiation, and it couldn’t be represented using multiple files, as users prefer.
+A [simple parameterization approach derived from Openshift’s design](/contributors/design-proposals/apps/OBSOLETE_templates.md) was approved because it was constrained in functionality and solved other problems (e.g., instantiation of resource variants by other controllers, [project templates in Openshift](https://github.com/openshift/training/blob/master/content/default-project-template.yaml)). That proposal explains some of the reasoning behind the design tradeoffs, as well as the [use cases](/contributors/design-proposals/apps/OBSOLETE_templates.md#use-cases). Work started, but was abandoned, though there is an independent [client-based implementation](https://github.com/InQuicker/ktmpl). However, the Template resource wrapped the resource specifications in another object, which is suboptimal, since transformations would then need to be able to deal with standalone resources, Lists of resources, and Templates, or would need to be applied post-instantiation, and it couldn’t be represented using multiple files, as users prefer.
 
 What is more problematic is that our client libraries, schema validators, yaml/json parsers/decoders, initializers, and protobuf encodings all require that all specified fields have valid values, so parameters cannot currently be left in non-string (e.g., int, bool) fields in actual resources. Additionally, the API server requires at least complete/final resource names to be specified, and strategic merge also requires all merge keys to be specified. Therefore, some amount of pre-instantiation (though not necessarily client-side) transformation is necessary to create valid resources, and we may want to explicitly store the output, or the fields should just contain the default values initially. Parameterized fields could be automatically converted to patches to produce valid resources. Such a transformation could be made reversible, unlike traditional substitution approaches, since the patches could be preserved (e.g., using annotations). The Template API supported the declaration of parameter names, display names, descriptions, default values, required/optional, and types (string, int, bool, base64), and both string and raw json substitutions. If we were to update that specification, we could use the same mechanism for both parameter validation and ConfigMap validation, so that the same mechanism could be used for env substitution and substitution of values of other fields. As mentioned in the [env validation issue](https://github.com/kubernetes/kubernetes/issues/4210#issuecomment-305555589), we should consider a subset of [JSON schema](http://json-schema.org/example1.html), which we’ll probably use for CRD. The only [unsupported attribute](https://tools.ietf.org/html/draft-wright-json-schema-validation-00) appears to be the display name, which is non-critical. [Base64 could be represented using media](http://json-schema.org/latest/json-schema-hypermedia.html#rfc.section.5.3.2). That could be useful as a common parameter schema to facilitate parameter discovery and documentation that is independent of the substitution syntax and mechanism ([example from Deployment Manager](https://github.com/GoogleCloudPlatform/deploymentmanager-samples/blob/master/templates/replicated_service.py.schema)).
 
 Without parameters how would we support a click-to-deploy experience? People who are kicking the tires, have undemanding use cases, are learning, etc. are unlikely to know what customization they want to perform initially, if they even need any. The main information users need to provide is the name prefix they want to apply. Otherwise, choosing among a few alternatives would suit their needs better than parameters. The overlay approach should support that pretty well. Beyond that, I suggest kicking users over to a Kubernetes-specific configuration wizard or schema-aware IDE, and/or support a fork workflow.
 
-The other application-definition [use cases mentioned in the Template proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/templates.md#use-cases) are achievable without parameterization, as well.
+The other application-definition [use cases mentioned in the Template proposal](/contributors/design-proposals/apps/OBSOLETE_templates.md#use-cases) are achievable without parameterization, as well.
 
 #### What about application configuration generation?
 

contributors/guide/README.md

@@ -129,7 +129,7 @@ For quick reference on contributor resources, we have a handy [contributor cheat
 
 It is best to contact your [SIG](#learn-about-sigs) for issues related to the SIG's topic. Your SIG will be able to help you much more quickly than a general question would.
 
-For general questions and troubleshooting, use the [kubernetes standard lines of communication](/communication.md) and work through the [kubernetes troubleshooting guide](https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/).
+For general questions and troubleshooting, use the [kubernetes standard lines of communication](/communication/README.md) and work through the [kubernetes troubleshooting guide](https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/).
 
 ## GitHub workflow
 

generator/list.tmpl

@@ -2,14 +2,14 @@
 # SIGs and Working Groups
 
 Most community activity is organized into Special Interest Groups (SIGs),
-time bounded Working Groups, and the [community meeting](communication.md#weekly-meeting).
+time bounded Working Groups, and the [community meeting](communication/README.md#weekly-meeting).
 
 SIGs follow these [guidelines](governance.md) although each of these groups may operate a little differently
 depending on their needs and workflow.
 
 Each group's material is in its subdirectory in this project.
 
-When the need arises, a [new SIG can be created](sig-creation-procedure.md)
+When the need arises, a [new SIG can be created](sig-governance.md#sig-creation-and-maintenance-procedure.md).
 
 ### Master SIG List