Add a README (#109)

olix0r · web-flow · commit c1764bec5b0f · 2022-05-25T08:29:36.000-07:00
This repo is missing a README.

This change adds a general overview of the repo and adds a markdown
linter to CI.

This change updates the copyright in the LICENSE file. It also fixes
Rust crate documentation generation so that all features are enabled by
docs.rs.

Signed-off-by: Oliver Gould &lt;ver@buoyant.io&gt;
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,6 +1,6 @@
 {
     "name": "linkerd2-proxy-api",
-    "image": "ghcr.io/linkerd/dev:v10",
+    "image": "ghcr.io/linkerd/dev:v11",
     "extensions": [
         "DavidAnson.vscode-markdownlint",
         "golang.go",
diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml
@@ -0,0 +1,20 @@
+name: markdown
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    paths:
+      - '**/*.md'
+      - .github/workflows/markdown.yml
+
+jobs:
+  markdownlint:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b
+      - uses: DavidAnson/markdownlint-cli2-action@744f913a124058ee903768d3adb92a4847e5d132
+        with:
+            globs: "**/*.md"
diff --git a/CHANGES.md b/CHANGES.md
@@ -25,8 +25,8 @@
 
 ## v0.2.0
 
-* Add the `io.linkerd.proxy.inbound.InboundServerPolicies` API to support server-side configuration
-  and policy.
+* Add the `io.linkerd.proxy.inbound.InboundServerPolicies` API to support
+  server-side configuration and policy.
 * Go: Update dependencies, including protoc and grpc
 * Rust: Update dependencies, including tonic v0.5
 * Rust: Add features for all APIs
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -17,7 +17,7 @@ contribution. See the [DCO](DCO) file for details.
 
 In practice, just add a line to every git commit message:
 
-```
+```text
 Signed-off-by: Jane Smith <jane.smith@example.com>
 ```
 
@@ -32,11 +32,13 @@ Do you have an improvement?
 
 1. Submit an [issue][issue] describing your proposed change.
 2. We will try to respond to your issue promptly.
-3. Fork this repo, develop and test your code changes. See the project's [README](README.md) for further information about working in this repository.
+3. Fork this repo, develop and test your code changes. See the project's
+   [README](README.md) for further information about working in this repository.
 4. Submit a pull request against this repo's `master` branch.
 5. Your branch may be merged once all configured checks pass, including:
     - The branch has passed tests in CI.
-    - A review from appropriate maintainers (see [MAINTAINERS.md](MAINTAINERS.md) and [GOVERNANCE.md](GOVERNANCE.md))
+    - A review from appropriate maintainers (see
+      [MAINTAINERS.md](MAINTAINERS.md) and [GOVERNANCE.md](GOVERNANCE.md))
 
 ## Committing ##
 
@@ -49,7 +51,7 @@ message.
 
 Finalized commit messages should be in the following format:
 
-```
+```text
 Subject
 
 Problem
@@ -72,12 +74,12 @@ Fixes #[GitHub issue ID]
 
 ##### Examples #####
 
-```
+```text
 bad: server disconnects should cause dst client disconnects.
 good: Propagate disconnects from source to destination
 ```
 
-```
+```text
 bad: support tls servers
 good: Introduce support for server-side TLS (#347)
 ```
diff --git a/Cargo.toml b/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.5.0"
 authors = ["Linkerd Developers <cncf-linkerd-dev@lists.cncf.io>"]
 license = "Apache-2.0"
 edition = "2021"
-description = "Linkerd2 Proxy API gRPC bindings and utilities"
+description = "Linkerd Proxy API gRPC bindings and utilities"
 homepage = "https://linkerd.io"
 repository = "https://github.com/linkerd/linkerd2-proxy-api"
 documentation = "https://docs.rs/linkerd2-proxy-api"
@@ -13,17 +13,18 @@ rust-version = "1.59"
 
 [features]
 default = []
-
-# Enable generation of arbitrary protos with quickcheck.
 arbitrary = ["quickcheck"]
-
 destination = ["http_types", "net", "prost-types", "tonic/codegen"]
 http_types = ["http", "thiserror"]
 identity = ["prost-types", "tonic/codegen"]
 inbound = ["net", "prost-types", "tonic/codegen"]
 net = ["ipnet", "thiserror"]
 tap = ["h2", "http_types", "net", "prost-types", "tonic/codegen"]
 
+[package.metadata.docs.rs]
+rustdoc-args = ["--cfg", "docsrs"]
+all-features = true
+
 [dependencies]
 h2 = { version = "0.3", optional = true }
 http = { version = "0.2", optional = true }
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
@@ -1 +1,3 @@
-See https://github.com/linkerd/linkerd2/blob/master/GOVERNANCE.md
+# Governance
+
+See <https://github.com/linkerd/linkerd2/blob/master/GOVERNANCE.md>.
diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2022 The Linkerd Authors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -1,14 +1,3 @@
-The Linkerd2 Proxy API maintainers are:
+# Maintainers
 
-* Oliver Gould <ver@buoyant.io> @olix0r (super-maintainer)
-* Kevin Lingerfelt <kl@buoyant.io> @klingerf (super-maintainer)
-
-<!--
-# Adding a new maintainer
-
-* Submit a PR modifying this file
-* Add maintainer to .github/CODEOWNERS
-* Obtain approvals per GOVERNANCE.md
-* Invite maintainer to https://github.com/orgs/linkerd/teams/linkerd2-maintainers/members
-* Invite maintainer to https://github.com/orgs/linkerd/people
--->
+See <https://github.com/linkerd/linkerd2/blob/master/MAINTAINERS.md>.
diff --git a/README.md b/README.md
@@ -0,0 +1,90 @@
+# Linkerd Proxy API
+
+This repo contains the gRPC bindings that the [Linkerd Proxy][proxy-gh] uses to
+communicate with the [Linkerd control plane][cp-gh].
+
+## APIs
+
+Generally, the proxy's APIs are Kubernetes-agnostic and expose abstractions that
+allow proxies to discover runtime configuration.
+
+### `destination`
+
+The destination API is used by proxies to discover information about outbound
+traffic. This configuration includes:
+
+* the protocol of the destination, if known
+* whether the destination is a load balanced service or individual endpoint
+* labels to describe the destination in telemetry
+* the mTLS identity of destination pods
+
+### `identity`
+
+The identity API is used by proxies to obtain TLS certificates used for
+authenticed pod-to-pod communication.
+
+### `inbound`
+
+The inbound API is used by the proxy to discover inbound serving
+policies--especially per-port authorization requirements.
+
+### `tap`
+
+The proxy can be configured to expose a gRPC server that allows the control
+plane to query metadata about live requests transiting the proxy.
+
+## Languages
+
+### Protobuf
+
+The [`./proto`](./proto) directory includes protobuf definitions.
+
+### Go
+
+The [`./go`](./go) directory contains statically generated Go bindings, which are
+generally used by [controller implementations][cp-gh].
+
+### Rust
+
+[![Crates.io][rs-crate-badge]][rs-crate-url]
+[![Documentation][rs-docs-badge]][rs-docs-url]
+[![License][rs-lic-badge]](LICENSE)
+
+This repository publishes the [**linkerd2-proxy-api** crate][rs-crate-url],
+which uses [`tonic`][tonic] to expose client and server implementations for each
+API. Each API may be enabled independently with cargo feature flags.
+
+The [proxy][proxy-gh] generally uses API clients. Some server implementations
+are also used by the [control plane][cp-gh].
+
+## Issues
+
+Issues may be opened in the [**linkerd2** repository][new-issue].
+
+## License
+
+    Copyright 2022 The Linkerd Authors
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+<!-- refs -->
+[cp-gh]: https://github.com/linkerd/linkerd2
+[new-issue]: https://github.com/linkerd/linkerd2/issues/new/choose
+[proxy-gh]: https://github.com/linkerd/linkerd2-proxy
+[tonic]: https://github.com/hyperium/tonic
+[rs-crate-badge]: https://img.shields.io/crates/v/linkerd2-proxy-api.svg
+[rs-crate-url]: https://crates.io/crates/linkerd2-proxy-api
+[rs-docs-badge]: https://docs.rs/linkerd2-proxy-api/badge.svg
+[rs-docs-url]: https://docs.rs/linkerd2-proxy-api
+[rs-docs-url]: https://img.shields.io/crates/l/linkerd2-proxy-api
+[rs-lic-badge]: https://img.shields.io/crates/l/linkerd2-proxy-api

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "linkerd2-proxy-api",`
`3`		`- "image": "ghcr.io/linkerd/dev:v10",`
	`3`	`+ "image": "ghcr.io/linkerd/dev:v11",`
`4`	`4`	`"extensions": [`
`5`	`5`	`"DavidAnson.vscode-markdownlint",`
`6`	`6`	`"golang.go",`