Initial project documentation (#32)

Wrote the initial project documentation for the `README.md` file that
includes...

1. ...an project introduction and motivation.
2. ...an overview of the project features.
3. ...an overview of the directory structure.
4. ...more detailed sections about all features.
5. ...some basic instructions how to use this template repository.
6. ...information about references used for this template repository.
7. ...information about how to contribute to this project.

Each directory documented in step 3 contains an individual documentation
with more detailed information about it.
The `package.json` file has been extended to include the
Yarn [1] / NPM [2] `workspaces` field.

[1]: https://classic.yarnpkg.com/docs/workspaces
[2]: https://docs.npmjs.com/cli/v7/using-npm/workspaces

Closes GH-31

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 <p align="center"><a href="https://github.com/svengreb/tmpl-go/releases/latest"><img src="https://img.shields.io/github/release/svengreb/tmpl-go.svg?style=flat-square&label=Release&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0"/></a></p>
 
-<p align="center">Changelog of the <a href="https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-template-repository" target="_blank">repository template</a> for Go projects.</p>
+<p align="center">Changelog of the <a href="https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-template-repository" target="_blank">template repository</a> for Go projects.</p>
 
 <!--lint disable no-duplicate-headings no-duplicate-headings-in-section-->
 

CONTRIBUTING.md

@@ -18,7 +18,7 @@ Before you continue with these contribution guidelines we highly recommend to re
 
 ### Repository Assignment
 
-tmpl is [a modular project][gh-profile-repo-search] of multiple [GitHub repository templates][gh-docs-repos-tmpl]. Each repository has a different focus for different use cases, project structures and programming languages.
+tmpl is [a modular project][gh-profile-repo-search] of multiple [template repositories][gh-docs-repos-tmpl]. Each repository has a different focus for different use cases, project structures and programming languages.
 
 **Please make sure to determine the correct repository before you continue!**
 Contributions related to a [specialized template][gh-profile-repo-search], like this one for [Go][], belong to the specific repository while contributions related to [the base template][gh-tmpl] are welcome in its repository. This helps all core team members, committers and maintainer to process every contribution faster without organization overhead.

api/README.md

@@ -0,0 +1,93 @@
+The `/api` directory stores API definition files like for example…
+
+- [Protocol Buffers][protobuf]
+- [OpenAPI][]/[Swagger][] specifications
+- [JSON schemas][json-schema]
+
+## Directory Structure
+
+A common practice is that API definition files are placed corresponding to the versioning model and path structure of the API. Please see the section below for a [practical usage example](#example) below for a common and practical usage pattern.
+
+## Example
+
+When using [Protocol Buffer][protobuf] the official style guide also recommends to lay out the directory structure for the `.proto` files based on the API version and [package paths][protobuf-docs-style#pkgs].
+
+This example assumes an API that has been designed to manage notes. It uses a [flat major based versioning format][gcloud-blog-api_versioning] starting at `v1`.
+The `api` directory structure could be constructed as follows:
+
+```raw
+api
+└─ v1
+   └─ notes
+      ├─ states
+      │  └─ kinds.proto
+      └─ notes.proto
+```
+
+The `api/v1/notes/notes.proto` and `api/v1/notes/states/kinds.proto` files could be defined as follows:
+
+```proto
+syntax = "proto3";
+
+package tmplgo.api.v1.notes;
+
+import "notes/states/kinds.proto";
+
+option go_package = "github.com/svengreb/tmpl-go/pkg/api/v1/notes";
+
+message Metadata {
+  string id = 1;
+  string name = 2;
+  string creator = 3;
+  google.protobuf.Timestamp created = 4;
+  google.protobuf.Timestamp modified = 5;
+}
+
+message Note {
+  Metadata metadata = 1;
+  repeated google.protobuf.Timestamp alerts = 2;
+  tmplgo.api.v1.notes.states.Kind state = 3;
+  Payload payload = 4;
+}
+
+message Payload {
+  string value = 1;
+}
+
+```
+
+```proto
+syntax = "proto3";
+
+package tmplgo.api.v1.notes.states;
+
+option go_package = "github.com/svengreb/tmpl-go/pkg/api/v1/notes/states";
+
+enum Kind {
+  UNKNOWN = 0;
+  OPEN = 1;
+  ARCHIVED = 2;
+}
+
+```
+
+## References
+
+Next to the experience with own projects and [golang-standards/project-layout][], many other large, production-grade and well-known projects of the API design and Go ecosystem have been used as references:
+
+- [Google APIs][gh-googleapis]
+- [Kubernetes][gh-kubernetes-tree-api]
+- [Moby][gh-moby-tree-api]
+- [NATS JetStream][gh-nats-jetstream-tree-schemas_source]
+
+[gcloud-blog-api_versioning]: https://cloud.google.com/blog/products/gcp/api-design-which-version-of-versioning-is-right-for-you
+[gh-googleapis]: https://github.com/googleapis/googleapis
+[gh-kubernetes-tree-api]: https://github.com/kubernetes/kubernetes/tree/master/api
+[gh-moby-tree-api]: https://github.com/moby/moby/tree/master/api
+[gh-nats-jetstream-tree-schemas_source]: https://github.com/nats-io/jetstream/tree/master/schemas_source
+[golang-standards/project-layout]: https://github.com/golang-standards/project-layout
+[json-schema]: https://json-schema.org
+[openapi]: https://www.openapis.org
+[protobuf-docs-style#pkgs]: https://developers.google.com/protocol-buffers/docs/style#packages
+[protobuf]: https://developers.google.com/protocol-buffers
+[swagger]: https://swagger.io

app/README.md

@@ -0,0 +1,50 @@
+The `/app` directory stores source code of project application(s) using the Go `main` package that can be compiled to the binary executable. It is often named `/cmd` instead, but because the name is not so appropriate and could lead to false assumptions it has been renamed for this template repository to better describe the actual content.
+
+## Directory Structure
+
+A common practice is that each application is placed in an individual directory that should match the name of the resulting binary executable.
+The structure always depends on the type and use case(s) of the application, but in general the code only consists of the `main` package and function that mainly imports and invokes reuseable code from the [`/internal`][gh-tree-internal] and [`/pkg`][gh-tree-pkg] directories.
+
+Code that is only relevant for an individual application like configurations, internal logic and commands can also be placed inside directories like `config`, `internal` and `internal/cmd`. In comparison, code that is reusable and could be imported from outside the module should never be placed in the application specific directory but [`/pkg`][gh-tree-pkg].
+Please see the [example](#example) below for a common and practical usage pattern.
+
+## Example
+
+Given the API defined in the [example of the `/api` directory][gh-blob-api-readme#example] and additionally assuming another service application named `notes-sync` the structure for the application could be created as follows:
+
+```raw
+app
+├─ notes
+│  ├─ config
+│  └─ internal
+│     └─ cmd
+│        ├─ archive
+│        ├─ create
+│        └─ delete
+└─ notes-sync
+    ├─ config
+    └─ internal
+        └─ cmd
+           ├─ export
+           └─ serve
+```
+
+## References
+
+Next to the experience with own projects and [golang-standards/project-layout][], many other large, production-grade and well-known projects of the Go ecosystem have been used as references:
+
+- [Kubernetes][gh-kubernetes-tree-cmd]
+- [Prometheus][gh-prometheus-tree-cmd]
+- [Moby][gh-moby-tree-cmd]
+- [Ardan Labs “Service Starter Kit“][ardanlabs/service]
+- [InfluxDB][gh-influxdb-tree-cmd]
+
+[ardanlabs/service]: https://github.com/ardanlabs/service/tree/master/app
+[gh-blob-api-readme#example]: https://github.com/svengreb/tmpl-go/blob/main/api/README.md#example
+[gh-influxdb-tree-cmd]: https://github.com/influxdata/influxdb/tree/master/cmd
+[gh-kubernetes-tree-cmd]: https://github.com/kubernetes/kubernetes/tree/master/cmd
+[gh-moby-tree-cmd]: https://github.com/moby/moby/tree/master/cmd
+[gh-prometheus-tree-cmd]: https://github.com/prometheus/prometheus/tree/master/cmd
+[gh-tree-internal]: https://github.com/svengreb/tmpl-go/tree/main/internal
+[gh-tree-pkg]: https://github.com/svengreb/tmpl-go/tree/main/pkg
+[golang-standards/project-layout]: https://github.com/golang-standards/project-layout

config/README.md

@@ -0,0 +1,76 @@
+The `/config` directory, also often named `contrib`, stores all configurations of any kind such as…
+
+- …container orchestration deployments — tools like Automated scaling and management systems like [Kubernetes][] or [Docker Compose][docker-compose] as well as tools to manage and process their configurations like [Kustomize][] and [Helm][].
+- …application configuration templates — reference, example or starter files that contain default values configurations of applications in the [`/app` directory][gh-tree-app].
+- …platform and distribution specific configurations — basic, platform specific configuration files for distribution or deployment purposes like for example [systemd][] units, process managers/supervisors or reverse proxies.
+
+## Directory Structure
+
+The files should be placed in separate directories based on their purpose or target technology. Please see the [example](#example) below for a common and practical usage pattern.
+
+## Example
+
+Given the [example of the `/api` directory][gh-blob-api-readme#example] the structure for some common configurations could be created as follows:
+
+```raw
+config
+├─ app
+│  └─ notes
+├─ deployment
+│  ├─ docker
+│  │  └─ compose
+│  └─ k8s
+│     ├─ base
+│     ├─ local
+│     ├─ development
+│     └─ production
+├─ packaging
+│  ├─ linux
+│  │  ├─ arch
+│  │  ├─ deb
+│  │  └─ flatpak
+│  └─ macos
+│     ├─ homebrew
+│     └─ pkg
+├─ platform
+│  ├─ nomad
+│  └─ systemd
+└─ security
+   ├─ certs
+   └─ secrets
+```
+
+## References
+
+Next to the experience with own projects and [golang-standards/project-layout][], many other large, production-grade and well-known projects of the Go ecosystem have been used as references:
+
+- [Moby][gh-moby-tree-contrib]
+- [Knative][gh-knative-tree-config]
+- [Ardan Labs “Service Starter Kit“][gh-ardanlabs/service-tree-zarf]
+- [Loki][gh-loki-tree-production]
+- [NATS][gh-nats-server-tree-docker]
+- [etcd][gh-etcd-tree-contrib]
+- Dapr ([Helm Charts][gh-dapr-tree-charts], [Grafana][gh-dapr-tree-grafana], [Docker][gh-dapr-tree-docker], [Swagger][gh-dapr-tree-swagger])
+- [Velero][gh-velero-tree-config]
+- [Kubernetes][gh-kubernetes-tree-hack]
+
+[docker-compose]: https://docs.docker.com/compose
+[gh-ardanlabs/service-tree-zarf]: https://github.com/ardanlabs/service/tree/master/zarf
+[gh-blob-api-readme#example]: https://github.com/svengreb/tmpl-go/blob/main/api/README.md#example
+[gh-dapr-tree-charts]: https://github.com/dapr/dapr/tree/master/charts/dapr
+[gh-dapr-tree-docker]: https://github.com/dapr/dapr/tree/master/docker
+[gh-dapr-tree-grafana]: https://github.com/dapr/dapr/tree/master/grafana
+[gh-dapr-tree-swagger]: https://github.com/dapr/dapr/tree/master/swagger
+[gh-etcd-tree-contrib]: https://github.com/etcd-io/etcd/tree/master/contrib
+[gh-knative-tree-config]: https://github.com/knative/serving/tree/master/config
+[gh-kubernetes-tree-hack]: https://github.com/kubernetes/kubernetes/tree/master/hack
+[gh-loki-tree-production]: https://github.com/grafana/loki/tree/master/production
+[gh-moby-tree-contrib]: https://github.com/moby/moby/tree/master/contrib
+[gh-nats-server-tree-docker]: https://github.com/nats-io/nats-server/tree/master/docker
+[gh-tree-app]: https://github.com/svengreb/tmpl-go/tree/main/app
+[gh-velero-tree-config]: https://github.com/vmware-tanzu/velero/tree/main/config
+[golang-standards/project-layout]: https://github.com/golang-standards/project-layout
+[helm]: https://helm.sh
+[kubernetes]: https://kubernetes.io
+[kustomize]: https://kustomize.io
+[systemd]: https://www.freedesktop.org/wiki/Software/systemd

docs/README.md

@@ -0,0 +1,73 @@
+The `/docs` directory stores project documentations, [runbooks][wikip-runbook] and any other kind of textual reference. These are often written in formats like [Markdown][wikip-md] and, depending on the project scope and technology stack, require a preprocessor. Note that documentations built with web based tools like [static site generators][jamstack-gens] (e.g. [Gatsby][], [Next.js][] or [Hugo][]) should be placed as own package in the [`/web` directory][gh-tree-web].
+
+## Directory Structure
+
+The layout always depends on the individual use case(s) of the project and when hosted on platforms like [GitHub Pages][gh-docs-pages] or [GitLab Pages][gl-pages]. A common practice is to store documentations in separate repositories, often in combination with static site generator configurations, for example the [official Kubernetes website][gh-kubernetes/website] or [Knative documentations][gh-knative/docs].
+
+## Example
+
+Given the [example of the `/api` directory][gh-blob-api-readme#example] the structure for some common configurations could be created as follows:
+
+```raw
+docs
+└─ notes
+   ├─ adr
+   │  ├─ api
+   │  ├─ architecture
+   │  ├─ cli
+   │  ├─ engineering
+   │  ├─ sdk
+   │  └─ specification
+   ├─ api
+   ├─ guides
+   │  ├─ development
+   │  ├─ roadmap
+   │  └─ runbook
+   └─ maintenance
+      ├─ release
+      │  └─ notes
+      ├─ runbook
+      └─ support
+```
+
+## References
+
+Next to the experience with own projects and [golang-standards/project-layout][], many other large, production-grade and well-known projects of the Go ecosystem have been used as references:
+
+- [Dapr][gh-dapr-tree-docs]
+- [Perkeep][gh-perkeep-tree-doc]
+- [Hugo][gh-hugo-tree-docs]
+- [Argo][gh-argo-tree-docs]
+- [Prometheus][gh-prometheus-tree-docs]
+- [Moby][gh-moby-tree-docs]
+- [Knative][gh-knative-tree-docs]
+- [MinIO][gh-minio-tree-docs]
+- [GoPass][gh-gopass-tree-docs]
+- [Flynn][gh-flynn-tree-docs]
+- [Flynn][gh-flynn-tree-docs]
+- [Velero][gh-velero-tree-design]
+
+[gatsby]: https://www.gatsbyjs.com
+[gh-argo-tree-docs]: https://github.com/argoproj/argo/tree/master/docs
+[gh-blob-api-readme#example]: https://github.com/svengreb/tmpl-go/blob/main/api/README.md#example
+[gh-dapr-tree-docs]: https://github.com/dapr/dapr/tree/master/docs
+[gh-docs-pages]: https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/about-github-pages
+[gh-flynn-tree-docs]: https://github.com/flynn/flynn/tree/master/docs
+[gh-gopass-tree-docs]: https://github.com/gopasspw/gopass/tree/master/docs
+[gh-hugo-tree-docs]: https://github.com/gohugoio/hugo/tree/master/docs
+[gh-knative-tree-docs]: https://github.com/knative/serving/tree/master/docs
+[gh-knative/docs]: https://github.com/knative/docs
+[gh-kubernetes/website]: https://github.com/kubernetes/website
+[gh-minio-tree-docs]: https://github.com/minio/minio/tree/master/docs
+[gh-moby-tree-docs]: https://github.com/moby/moby/tree/master/docs
+[gh-perkeep-tree-doc]: https://github.com/perkeep/perkeep/tree/master/doc
+[gh-prometheus-tree-docs]: https://github.com/prometheus/prometheus/tree/master/docs
+[gh-tree-web]: https://github.com/svengreb/tmpl-go/tree/main/web
+[gh-velero-tree-design]: https://github.com/vmware-tanzu/velero/tree/main/design
+[gl-pages]: https://about.gitlab.com/stages-devops-lifecycle/pages
+[golang-standards/project-layout]: https://github.com/golang-standards/project-layout
+[hugo]: https://gohugo.io
+[jamstack-gens]: https://jamstack.org/generators
+[next.js]: https://jamstack.org/generators/next
+[wikip-md]: https://en.wikipedia.org/wiki/Markdown
+[wikip-runbook]: https://en.wikipedia.org/wiki/Runbook

examples/README.md

@@ -0,0 +1,30 @@
+The `/examples` directory stores examples for provided APIs that are defined in the [`/api` directory][gh-tree-api], public packages from the [`/pkg` directory][gh-tree-pkg], ways to use and run applications from the [`/app` directory][gh-tree-app] or to demonstrate the integration with other applications, platforms or systems.
+
+## Directory Structure
+
+A common practice is that each example is placed in an individual directory whose name matches its use case. Please see the [example](#example) below for a common and practical usage pattern.
+
+## Example
+
+Given the API defined in the [example of the `/api` directory][gh-blob-api-readme#example] the structure could be created as follows:
+
+```raw
+examples
+├─ auto-backup
+└─ synchronization
+```
+
+## References
+
+Next to the experience with own projects and [golang-standards/project-layout][], many other large, production-grade and well-known projects of the Go ecosystem have been used as references:
+
+- [NATS][gh-nats-tree-examples]
+- [Velero][gh-velero-tree-examples]
+
+[gh-blob-api-readme#example]: https://github.com/svengreb/tmpl-go/blob/main/api/README.md#example
+[gh-nats-tree-examples]: https://github.com/nats-io/nats.go/tree/master/examples
+[gh-tree-api]: https://github.com/svengreb/tmpl-go/tree/main/api
+[gh-tree-app]: https://github.com/svengreb/tmpl-go/tree/main/app
+[gh-tree-pkg]: https://github.com/svengreb/tmpl-go/tree/main/pkg
+[gh-velero-tree-examples]: https://github.com/vmware-tanzu/velero/tree/main/examples
+[golang-standards/project-layout]: https://github.com/golang-standards/project-layout

internal/README.md

@@ -0,0 +1,53 @@
+The `/internal` directory stores non-exported (“private“) application and package code that, in comparison to code in the [`/pkg` directory][gh-tree-pkg], can never be imported in other modules. As of [Go version 1.4 the compiler itself enforces the `internal` directory naming pattern][go-doc-rln-1.4#int_pkg] and prevents all packages within this directory to be imported by other modules outside the module in which they reside. Note that this pattern it not limited to the top level `/internal` directory but to any nested `internal` directory within the module.
+
+## Directory Structure
+
+A common practice is that the `/internal` directory contains sub-directories to separate code targeted only for individual applications using the same pattern like the [`/app` directory][gh-tree-pkg] or module-wide code like stored in the [`/pkg` directory][gh-tree-pkg].
+
+each application is placed in an individual directory that should match the name of the resulting binary executable.
+The structure always depends on the type and use case(s) of the application, but in general the code only consists of the `main` package and function that mainly imports and invokes reuseable code from the [`/internal`][gh-tree-internal] and directories. This helps to better visualize the intended package use and distinguish shared and non-shared code.
+
+## Example
+
+Given the [example of the `/api` directory][gh-blob-api-readme#example] the structure could be created as follows:
+
+```raw
+internal
+├─ app
+│  ├─ notes
+│  └─ notes-sync
+└─ pkg
+   ├─ platform
+   │  ├─ http
+   │  ├─ logging
+   │  ├─ messaging
+   │  └─ transport
+   ├─ product
+   │  └─ store
+   └─ support
+      ├─ data
+      └─ project
+```
+
+## References
+
+Next to the experience with own projects and [golang-standards/project-layout][], many other large, production-grade and well-known projects of the Go ecosystem have been used as references:
+
+- [Terraform][gh-terraform-tree-internal]
+- [NATS][gh-nats-server-tree-internal]
+- [InfluxDB][gh-influxdb-tree-internal]
+- [Perkeep][gh-perkeep-tree-internal]
+- [Jaeger][gh-jaeger-tree-internal]
+- [Waypoint][gh-waypoint-tree-internal-pkg]
+
+[gh-blob-api-readme#example]: https://github.com/svengreb/tmpl-go/blob/main/api/README.md#example
+[gh-influxdb-tree-internal]: https://github.com/influxdata/influxdb/tree/master/internal
+[gh-jaeger-tree-internal]: https://github.com/jaegertracing/jaeger/tree/master/internal
+[gh-nats-server-tree-internal]: https://github.com/nats-io/nats-server/tree/master/internal
+[gh-perkeep-tree-internal]: https://github.com/perkeep/perkeep/tree/master/internal
+[gh-terraform-tree-internal]: https://github.com/hashicorp/terraform/tree/master/internal
+[gh-tree-internal]: https://github.com/svengreb/tmpl-go/tree/main/internal
+[gh-tree-pkg]: https://github.com/svengreb/tmpl-go/tree/main/pkg
+[gh-waypoint-tree-internal-pkg]: https://github.com/hashicorp/waypoint/tree/main/internal/pkg
+[go-doc-rln-1.4#int_pkg]: https://golang.org/doc/go1.4#internalpackages
+[golang-standards/project-layout]: https://github.com/golang-standards/project-layout