diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a60d72c72e..9b55be796f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -105,10 +105,10 @@ If a dependency is added or change, run `go mod tidy` to update `go.mod` and `go ## Developer Documentation -Documentation about the Consul code base is under [./contributing], +Documentation about the Consul code base is under [./docs], and godoc package document can be read at [pkg.go.dev/github.com/hashicorp/consul]. -[./contributing]: ../contributing/README.md +[./docs]: ../docs/README.md [pkg.go.dev/github.com/hashicorp/consul]: https://pkg.go.dev/github.com/hashicorp/consul ### Checklists @@ -116,5 +116,5 @@ and godoc package document can be read at [pkg.go.dev/github.com/hashicorp/consu Some common changes that many PRs require such as adding config fields, are documented through checklists. -Please check in `contributing/` for any `checklist-*.md` files that might help +Please check in [docs/](../docs/) for any `checklist-*.md` files that might help with your change. diff --git a/INTERNALS.md b/INTERNALS.md index d5043a16a4..efa95dab39 100644 --- a/INTERNALS.md +++ b/INTERNALS.md @@ -1 +1 @@ -Moved to [contributing/README.md](./contributing/README.md). +Moved to [docs/README.md](./docs/README.md). diff --git a/contributing/INTERNALS.md b/contributing/INTERNALS.md index 2a0114d3db..0deb6675cb 100644 --- a/contributing/INTERNALS.md +++ b/contributing/INTERNALS.md @@ -1 +1 @@ -Moved to [README.md](./README.md). +Moved to [docs/README.md](../docs/README.md). diff --git a/contributing/README.md b/contributing/README.md index 2f0f63dff3..5ab5e80d30 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -1,81 +1 @@ -# Contributing to Consul - -See [our contributing guide](../.github/CONTRIBUTING.md) to get started. - -This directory contains documentation intended for anyone interested in -understanding, and contributing changes to, the Consul codebase. - -## Overview - -This documentation is organized into the following categories. Each category is -either a significant architectural layer, or major functional area of Consul. -These documents assume a basic understanding of Consul's feature set, which can -found in the public [user documentation]. - -[user documentation]: https://www.consul.io/docs - -![Overview](./overview.svg) - -[source](./overview.mmd) - -## Contents - -1. [Command-Line Interface (CLI)](./cli) -1. [HTTP API](./http-api) -1. [Agent Configuration](./config) -1. [RPC](./rpc) -1. [Cluster Persistence](./persistence) -1. [Client Agent](./client-agent) -1. [Service Discovery](./service-discovery) -1. [Service Mesh (Connect)](./service-mesh) -1. [Cluster Membership](./cluster-membership) -1. [Key/Value Store](./kv) -1. [ACL](./acl) -1. [Multi-Cluster Federation](./cluster-federation) - -Also see the [FAQ](./faq.md). - -## Important Directories - -Most top level directories contain Go source code. The directories listed below -contain other important source related to Consul. - -* [ui] contains the source code for the Consul UI. -* [website] contains the source for [consul.io](https://www.consul.io/). A pull requests - can update the source code and Consul's documentation at the same time. -* [.circleci] and [.github] contain the source for our CI and GitHub repository - automation. -* [.changelog] contains markdown files that are used by [hashicorp/go-changelog] to produce the - [CHANGELOG.md]. -* [build-support] contains bash functions and scripts used to automate. - development tasks. Generally these scripts are called from the [GNUmakefile]. -* [grafana] contains the source for a [Grafana dashboard] that can be used to - monitor Consul. - -[ui]: https://github.com/hashicorp/consul/tree/main/ui -[website]: https://github.com/hashicorp/consul/tree/main/website -[.circleci]: https://github.com/hashicorp/consul/tree/main/.circleci -[.github]: https://github.com/hashicorp/consul/tree/main/.github -[.changelog]: https://github.com/hashicorp/consul/tree/main/.changelog -[hashicorp/go-changelog]: https://github.com/hashicorp/go-changelog -[CHANGELOG.md]: https://github.com/hashicorp/consul/blob/main/CHANGELOG.md -[build-support]: https://github.com/hashicorp/consul/tree/main/build-support -[GNUmakefile]: https://github.com/hashicorp/consul/tree/main/GNUmakefile -[Grafana dashboard]: https://grafana.com/grafana/dashboards -[grafana]: https://github.com/hashicorp/consul/tree/main/grafana - - -## Contributing to these docs - -This section is meta documentation about contributing to these docs. - -### Diagrams - -The diagrams in these documents are created using the [mermaid-js live editor]. -The [mermaid-js docs] provide a complete reference for how to create and edit -the diagrams. Use the [consul-mermaid-theme.json] (paste it into the Config tab -in the editor) to maintain a consistent Consul style for the diagrams. - -[mermaid-js live editor]: https://mermaid-js.github.io/mermaid-live-editor/edit/ -[mermaid-js docs]: https://mermaid-js.github.io/mermaid/ -[consul-mermaid-theme.json]: ./consul-mermaid-theme.json +Moved to [docs](../docs/README.md). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..8c1148ec2a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,81 @@ +# Consul Developer Documentation + +See [our contributing guide](../.github/CONTRIBUTING.md) to get started. + +This directory contains documentation intended for anyone interested in +understanding, and contributing changes to, the Consul codebase. + +## Overview + +This documentation is organized into the following categories. Each category is +either a significant architectural layer, or major functional area of Consul. +These documents assume a basic understanding of Consul's feature set, which can +be found in the public [user documentation]. + +[user documentation]: https://www.consul.io/docs + +![Overview](./overview.svg) + +[source](./overview.mmd) + +## Contents + +1. [Command-Line Interface (CLI)](./cli) +1. [HTTP API](./http-api) +1. [Agent Configuration](./config) +1. [RPC](./rpc) +1. [Cluster Persistence](./persistence) +1. [Client Agent](./client-agent) +1. [Service Discovery](./service-discovery) +1. [Service Mesh (Connect)](./service-mesh) +1. [Cluster Membership](./cluster-membership) +1. [Key/Value Store](./kv) +1. [ACL](./acl) +1. [Multi-Cluster Federation](./cluster-federation) + +Also see the [FAQ](./faq.md). + +## Important Directories + +Most top level directories contain Go source code. The directories listed below +contain other important source related to Consul. + +* [ui] contains the source code for the Consul UI. +* [website] contains the source for [consul.io](https://www.consul.io/). A pull requests + can update the source code and Consul's documentation at the same time. +* [.circleci] and [.github] contain the source for our CI and GitHub repository + automation. +* [.changelog] contains markdown files that are used by [hashicorp/go-changelog] to produce the + [CHANGELOG.md]. +* [build-support] contains bash functions and scripts used to automate. + development tasks. Generally these scripts are called from the [GNUmakefile]. +* [grafana] contains the source for a [Grafana dashboard] that can be used to + monitor Consul. + +[ui]: https://github.com/hashicorp/consul/tree/main/ui +[website]: https://github.com/hashicorp/consul/tree/main/website +[.circleci]: https://github.com/hashicorp/consul/tree/main/.circleci +[.github]: https://github.com/hashicorp/consul/tree/main/.github +[.changelog]: https://github.com/hashicorp/consul/tree/main/.changelog +[hashicorp/go-changelog]: https://github.com/hashicorp/go-changelog +[CHANGELOG.md]: https://github.com/hashicorp/consul/blob/main/CHANGELOG.md +[build-support]: https://github.com/hashicorp/consul/tree/main/build-support +[GNUmakefile]: https://github.com/hashicorp/consul/tree/main/GNUmakefile +[Grafana dashboard]: https://grafana.com/grafana/dashboards +[grafana]: https://github.com/hashicorp/consul/tree/main/grafana + + +## Contributing to these docs + +This section is meta documentation about contributing to these docs. + +### Diagrams + +The diagrams in these documents are created using the [mermaid-js live editor]. +The [mermaid-js docs] provide a complete reference for how to create and edit +the diagrams. Use the [consul-mermaid-theme.json] (paste it into the Config tab +in the editor) to maintain a consistent Consul style for the diagrams. + +[mermaid-js live editor]: https://mermaid-js.github.io/mermaid-live-editor/edit/ +[mermaid-js docs]: https://mermaid-js.github.io/mermaid/ +[consul-mermaid-theme.json]: ./consul-mermaid-theme.json diff --git a/contributing/acl/README.md b/docs/acl/README.md similarity index 100% rename from contributing/acl/README.md rename to docs/acl/README.md diff --git a/contributing/acl/erd.mmd b/docs/acl/erd.mmd similarity index 100% rename from contributing/acl/erd.mmd rename to docs/acl/erd.mmd diff --git a/contributing/acl/erd.svg b/docs/acl/erd.svg similarity index 100% rename from contributing/acl/erd.svg rename to docs/acl/erd.svg diff --git a/contributing/cli/README.md b/docs/cli/README.md similarity index 100% rename from contributing/cli/README.md rename to docs/cli/README.md diff --git a/contributing/client-agent/README.md b/docs/client-agent/README.md similarity index 100% rename from contributing/client-agent/README.md rename to docs/client-agent/README.md diff --git a/contributing/cluster-federation/README.md b/docs/cluster-federation/README.md similarity index 100% rename from contributing/cluster-federation/README.md rename to docs/cluster-federation/README.md diff --git a/contributing/cluster-federation/network-areas/README.md b/docs/cluster-federation/network-areas/README.md similarity index 100% rename from contributing/cluster-federation/network-areas/README.md rename to docs/cluster-federation/network-areas/README.md diff --git a/contributing/cluster-membership/README.md b/docs/cluster-membership/README.md similarity index 100% rename from contributing/cluster-membership/README.md rename to docs/cluster-membership/README.md diff --git a/contributing/config/README.md b/docs/config/README.md similarity index 100% rename from contributing/config/README.md rename to docs/config/README.md diff --git a/contributing/config/checklist-adding-config-fields.md b/docs/config/checklist-adding-config-fields.md similarity index 100% rename from contributing/config/checklist-adding-config-fields.md rename to docs/config/checklist-adding-config-fields.md diff --git a/contributing/consul-mermaid-theme.json b/docs/consul-mermaid-theme.json similarity index 100% rename from contributing/consul-mermaid-theme.json rename to docs/consul-mermaid-theme.json diff --git a/contributing/faq.md b/docs/faq.md similarity index 100% rename from contributing/faq.md rename to docs/faq.md diff --git a/contributing/http-api/README.md b/docs/http-api/README.md similarity index 100% rename from contributing/http-api/README.md rename to docs/http-api/README.md diff --git a/contributing/overview.mmd b/docs/overview.mmd similarity index 100% rename from contributing/overview.mmd rename to docs/overview.mmd diff --git a/contributing/overview.svg b/docs/overview.svg similarity index 100% rename from contributing/overview.svg rename to docs/overview.svg diff --git a/contributing/persistence/README.md b/docs/persistence/README.md similarity index 100% rename from contributing/persistence/README.md rename to docs/persistence/README.md diff --git a/contributing/persistence/overview.mmd b/docs/persistence/overview.mmd similarity index 100% rename from contributing/persistence/overview.mmd rename to docs/persistence/overview.mmd diff --git a/contributing/persistence/overview.svg b/docs/persistence/overview.svg similarity index 100% rename from contributing/persistence/overview.svg rename to docs/persistence/overview.svg diff --git a/contributing/rpc/README.md b/docs/rpc/README.md similarity index 100% rename from contributing/rpc/README.md rename to docs/rpc/README.md diff --git a/contributing/rpc/routing.mmd b/docs/rpc/routing.mmd similarity index 100% rename from contributing/rpc/routing.mmd rename to docs/rpc/routing.mmd diff --git a/contributing/rpc/routing.svg b/docs/rpc/routing.svg similarity index 100% rename from contributing/rpc/routing.svg rename to docs/rpc/routing.svg diff --git a/contributing/rpc/streaming/README.md b/docs/rpc/streaming/README.md similarity index 100% rename from contributing/rpc/streaming/README.md rename to docs/rpc/streaming/README.md diff --git a/contributing/rpc/streaming/adding-a-topic.md b/docs/rpc/streaming/adding-a-topic.md similarity index 100% rename from contributing/rpc/streaming/adding-a-topic.md rename to docs/rpc/streaming/adding-a-topic.md diff --git a/contributing/rpc/streaming/event-filtering.mmd b/docs/rpc/streaming/event-filtering.mmd similarity index 100% rename from contributing/rpc/streaming/event-filtering.mmd rename to docs/rpc/streaming/event-filtering.mmd diff --git a/contributing/rpc/streaming/event-filtering.svg b/docs/rpc/streaming/event-filtering.svg similarity index 100% rename from contributing/rpc/streaming/event-filtering.svg rename to docs/rpc/streaming/event-filtering.svg diff --git a/contributing/rpc/streaming/event-publisher-layout.mmd b/docs/rpc/streaming/event-publisher-layout.mmd similarity index 100% rename from contributing/rpc/streaming/event-publisher-layout.mmd rename to docs/rpc/streaming/event-publisher-layout.mmd diff --git a/contributing/rpc/streaming/event-publisher-layout.svg b/docs/rpc/streaming/event-publisher-layout.svg similarity index 100% rename from contributing/rpc/streaming/event-publisher-layout.svg rename to docs/rpc/streaming/event-publisher-layout.svg diff --git a/contributing/rpc/streaming/framing-events.mmd b/docs/rpc/streaming/framing-events.mmd similarity index 100% rename from contributing/rpc/streaming/framing-events.mmd rename to docs/rpc/streaming/framing-events.mmd diff --git a/contributing/rpc/streaming/framing-events.svg b/docs/rpc/streaming/framing-events.svg similarity index 100% rename from contributing/rpc/streaming/framing-events.svg rename to docs/rpc/streaming/framing-events.svg diff --git a/contributing/rpc/streaming/overview.mmd b/docs/rpc/streaming/overview.mmd similarity index 100% rename from contributing/rpc/streaming/overview.mmd rename to docs/rpc/streaming/overview.mmd diff --git a/contributing/rpc/streaming/overview.svg b/docs/rpc/streaming/overview.svg similarity index 100% rename from contributing/rpc/streaming/overview.svg rename to docs/rpc/streaming/overview.svg diff --git a/contributing/service-discovery/README.md b/docs/service-discovery/README.md similarity index 100% rename from contributing/service-discovery/README.md rename to docs/service-discovery/README.md diff --git a/contributing/service-discovery/catalog-2.mmd b/docs/service-discovery/catalog-2.mmd similarity index 100% rename from contributing/service-discovery/catalog-2.mmd rename to docs/service-discovery/catalog-2.mmd diff --git a/contributing/service-discovery/catalog.md b/docs/service-discovery/catalog.md similarity index 100% rename from contributing/service-discovery/catalog.md rename to docs/service-discovery/catalog.md diff --git a/contributing/service-discovery/catalog.mmd b/docs/service-discovery/catalog.mmd similarity index 100% rename from contributing/service-discovery/catalog.mmd rename to docs/service-discovery/catalog.mmd diff --git a/contributing/service-discovery/dns.md b/docs/service-discovery/dns.md similarity index 100% rename from contributing/service-discovery/dns.md rename to docs/service-discovery/dns.md diff --git a/contributing/service-discovery/health-checks.md b/docs/service-discovery/health-checks.md similarity index 100% rename from contributing/service-discovery/health-checks.md rename to docs/service-discovery/health-checks.md diff --git a/contributing/service-mesh/README.md b/docs/service-mesh/README.md similarity index 100% rename from contributing/service-mesh/README.md rename to docs/service-mesh/README.md diff --git a/contributing/service-mesh/xds.md b/docs/service-mesh/xds.md similarity index 100% rename from contributing/service-mesh/xds.md rename to docs/service-mesh/xds.md