more notes and notes in major directories

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.

api/README.md

@@ -0,0 +1,3 @@
+# `/api`
+
+OpenAPI/Swagger specs, JSON schema files, protocol definition files.

assets/README.md

@@ -0,0 +1,3 @@
+# `/assets`
+
+Other assets to go along with your repository.

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.

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.

configs/README.md

@@ -0,0 +1,5 @@
+# `/configs`
+
+Configuration file templates or default configs.
+
+Put your `confd` or `consule-template` template files here.

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).

docs/README.md

@@ -0,0 +1,3 @@
+# `/docs`
+
+Design and user documents (in addition to your godoc generated documentation).

examples/README.md

@@ -0,0 +1,3 @@
+# `/examples`
+
+Examples for your applications and/or public libraries.

githooks/README.md

@@ -0,0 +1,3 @@
+# `/githooks`
+
+Git hooks.

init/README.md

@@ -0,0 +1,3 @@
+# `/init`
+
+System init (systemd, upstart, sysv) and process manager/supervisor (runit, supervisord) configs.

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`).

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 :-)

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.

test/README.md

@@ -0,0 +1,3 @@
+# `/test`
+
+Additional external test apps and test data.

third_party/README.md

@@ -0,0 +1,3 @@
+# `/third_party`
+
+External helper tools, forked code and other 3rd party utilities (e.g., Swagger UI).

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.

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.

web/README.md

@@ -0,0 +1,3 @@
+# `/web`
+
+Web application specific components: static web assets, server side templates and SPAs.