From 6298595c9e71620dc6d1c6b26c2e9b529c6ece8b Mon Sep 17 00:00:00 2001 From: Kyle Quest Date: Sat, 24 Mar 2018 15:55:43 -0700 Subject: [PATCH] more notes and notes in major directories --- README.md | 17 +++++++++++++---- api/README.md | 3 +++ assets/README.md | 3 +++ build/README.md | 7 +++++++ cmd/README.md | 9 +++++++++ configs/README.md | 5 +++++ deployments/README.md | 3 +++ docs/README.md | 3 +++ examples/README.md | 3 +++ githooks/README.md | 3 +++ init/README.md | 3 +++ internal/README.md | 5 +++++ pkg/README.md | 5 +++++ scripts/README.md | 5 +++++ test/README.md | 3 +++ third_party/README.md | 3 +++ tools/README.md | 3 +++ vendor/README.md | 5 +++++ web/README.md | 3 +++ 19 files changed, 87 insertions(+), 4 deletions(-) create mode 100644 api/README.md create mode 100644 assets/README.md create mode 100644 build/README.md create mode 100644 cmd/README.md create mode 100644 configs/README.md create mode 100644 deployments/README.md create mode 100644 docs/README.md create mode 100644 examples/README.md create mode 100644 githooks/README.md create mode 100644 init/README.md create mode 100644 internal/README.md create mode 100644 pkg/README.md create mode 100644 scripts/README.md create mode 100644 test/README.md create mode 100644 third_party/README.md create mode 100644 tools/README.md create mode 100644 vendor/README.md create mode 100644 web/README.md diff --git a/README.md b/README.md index 1f9b47b..e39983f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Standard Go Project Layout -This is a basic layout for Go application projects. It represents the most common directory structure with a number of small enhancements along with several supporting directories common to any real world application. +This is a basic layout for Go application projects. It represents the most common directory structure with a number of small enhancements along with several supporting directories common to any real world application. + +This project layout is intentionally generic and it doesn't try to impose a specific Go package structure. Clone the repository, keep what you need and delete everything else! @@ -14,13 +16,13 @@ Main applications for this project. The directory name for each application should match the name of the executable you want to have (e.g., `/cmd/myapp`). -Don't put a lot of code in the application directory. If you think the code can be imported and used in other projects, then it should live in the `/pkg` directory. If the code is not reusable or if you don't want others to reuse it, put that code in the `/internal` directory. You'll be surprised what others will do, so be explicit about your intentions! +Don't put a lot of code in the application directory. If you think the code can be imported and used in other projects, then it should live in the `/pkg` directory. If the code is not reusable or if you don't want others to reuse it, put that code in the `/internal` directory. You'll be surprised what others will do, so be explicit about your intentions! -It's common to have a small main function that imports and invokes the code from the `/internal` and `/pkg` directories. +It's common to have a small `main` function that imports and invokes the code from the `/internal` and `/pkg` directories and nothing else. ### `/internal` -Private application and library code. +Private application and library code. This is the code you don't want others importing in their applications or libraries. Put your actual application code in the `/internal/app` directory (e.g., `/internal/app/myapp`) and the code shared by those apps in the `/internal/pkg` directory (e.g., `/internal/pkg/myprivlib`). @@ -108,6 +110,13 @@ Git hooks. Other assets to go along with your repository. +## Directories You Shouldn't Have + +### `/src` + +Some Go projects do have a `src` folder, but it usually happens when the devs came from the Java world where it's a common pattern. If you can help yourself try not to adopt this Java pattern. You really don't want your Go code or Go projects to look like Java :-) + + ## Badges * [Go Report Card](https://goreportcard.com/) - It will scan your code with `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` and `misspell`. Replace `github.com/golang-standards/project-layout` with your project reference. diff --git a/api/README.md b/api/README.md new file mode 100644 index 0000000..5bc898c --- /dev/null +++ b/api/README.md @@ -0,0 +1,3 @@ +# `/api` + +OpenAPI/Swagger specs, JSON schema files, protocol definition files. diff --git a/assets/README.md b/assets/README.md new file mode 100644 index 0000000..97ed16c --- /dev/null +++ b/assets/README.md @@ -0,0 +1,3 @@ +# `/assets` + +Other assets to go along with your repository. diff --git a/build/README.md b/build/README.md new file mode 100644 index 0000000..91ce6ac --- /dev/null +++ b/build/README.md @@ -0,0 +1,7 @@ +# `/build` + +Packaging and Continous Integration. + +Put your cloud (AMI), container (Docker), OS (deb, rpm, pkg) package configurations and scripts in the `/build/package` directory. + +Put your CI (travis, circle, drone) configurations and scripts in the `/build/ci` directory. diff --git a/cmd/README.md b/cmd/README.md new file mode 100644 index 0000000..2d6a555 --- /dev/null +++ b/cmd/README.md @@ -0,0 +1,9 @@ +# `/cmd` + +Main applications for this project. + +The directory name for each application should match the name of the executable you want to have (e.g., `/cmd/myapp`). + +Don't put a lot of code in the application directory. If you think the code can be imported and used in other projects, then it should live in the `/pkg` directory. If the code is not reusable or if you don't want others to reuse it, put that code in the `/internal` directory. You'll be surprised what others will do, so be explicit about your intentions! + +It's common to have a small `main` function that imports and invokes the code from the `/internal` and `/pkg` directories and nothing else. diff --git a/configs/README.md b/configs/README.md new file mode 100644 index 0000000..3701d7c --- /dev/null +++ b/configs/README.md @@ -0,0 +1,5 @@ +# `/configs` + +Configuration file templates or default configs. + +Put your `confd` or `consule-template` template files here. diff --git a/deployments/README.md b/deployments/README.md new file mode 100644 index 0000000..c6e4ecb --- /dev/null +++ b/deployments/README.md @@ -0,0 +1,3 @@ +# `/deployments` + +IaaS, PaaS, system and container orchestration deployment configurations and templates (docker-compose, kubernetes/helm, mesos, terraform, bosh). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..10d4502 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# `/docs` + +Design and user documents (in addition to your godoc generated documentation). diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..d323b00 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,3 @@ +# `/examples` + +Examples for your applications and/or public libraries. diff --git a/githooks/README.md b/githooks/README.md new file mode 100644 index 0000000..741899a --- /dev/null +++ b/githooks/README.md @@ -0,0 +1,3 @@ +# `/githooks` + +Git hooks. diff --git a/init/README.md b/init/README.md new file mode 100644 index 0000000..1544dec --- /dev/null +++ b/init/README.md @@ -0,0 +1,3 @@ +# `/init` + +System init (systemd, upstart, sysv) and process manager/supervisor (runit, supervisord) configs. diff --git a/internal/README.md b/internal/README.md new file mode 100644 index 0000000..5bba3ac --- /dev/null +++ b/internal/README.md @@ -0,0 +1,5 @@ +# `/internal` + +Private application and library code. This is the code you don't want others importing in their applications or libraries. + +Put your actual application code in the `/internal/app` directory (e.g., `/internal/app/myapp`) and the code shared by those apps in the `/internal/pkg` directory (e.g., `/internal/pkg/myprivlib`). diff --git a/pkg/README.md b/pkg/README.md new file mode 100644 index 0000000..942404c --- /dev/null +++ b/pkg/README.md @@ -0,0 +1,5 @@ +# `/pkg` + +Library code that's safe to use by external applications (e.g., `/pkg/mypubliclib`). + +Other projects will import these libraries expecting them to work, so think twice before you put something here :-) diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..3690150 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,5 @@ +# `/scripts` + +Scripts to perform various build, install, analysis, etc operations. + +These scripts keep the root level Makefile small and simple. diff --git a/test/README.md b/test/README.md new file mode 100644 index 0000000..14964a7 --- /dev/null +++ b/test/README.md @@ -0,0 +1,3 @@ +# `/test` + +Additional external test apps and test data. diff --git a/third_party/README.md b/third_party/README.md new file mode 100644 index 0000000..cc530ca --- /dev/null +++ b/third_party/README.md @@ -0,0 +1,3 @@ +# `/third_party` + +External helper tools, forked code and other 3rd party utilities (e.g., Swagger UI). diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000..f87cf27 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,3 @@ +# `/tools` + +Supporting tools for this project. Note that these tools can import code from the `/pkg` and `/internal` directories. diff --git a/vendor/README.md b/vendor/README.md new file mode 100644 index 0000000..62bd810 --- /dev/null +++ b/vendor/README.md @@ -0,0 +1,5 @@ +# `/vendor` + +Application dependencies (managed manually or by your favorite dependency management tool). + +Don't commit your application dependencies if you are building a library. diff --git a/web/README.md b/web/README.md new file mode 100644 index 0000000..020b468 --- /dev/null +++ b/web/README.md @@ -0,0 +1,3 @@ +# `/web` + +Web application specific components: static web assets, server side templates and SPAs.