internal/ and cmd/ Layout

## The rule, stated exactly An import of a path containing the element `internal` is disallowed if the importing code is outside the tree rooted at the parent of the `internal` directory. Every word of that matters: - **element**, not substring — a directory called `internals` or `internalstuff` is an ordinary directory with no special meaning. Only a path element that is exactly `internal` triggers the rule. - **the parent of internal/**, not `internal/` itself — the permitted region is the whole subtree that contains the `internal/` directory, not just the directory next to it. - **the importing code**, not the running code — this is a build-time decision made from import paths alone. ## Where the boundary lands Take a module whose path is `github.com/acme/svc`: ``` github.com/acme/svc/ cmd/api/main.go pkg/client/client.go internal/store/store.go ``` `internal/`'s parent is the module root, so *every* package under `github.com/acme/svc` may import `github.com/acme/svc/internal/store`: `cmd/api`, `pkg/client`, and any test in them. No package outside that path prefix may — not another repository, not another module belonging to the same team. Now push the `internal/` down a level: ``` github.com/acme/svc/pkg/parser/internal/lex ``` The parent is `pkg/parser`, so only code under `github.com/acme/svc/pkg/parser` can import `.../internal/lex`. `cmd/api` cannot, even though it lives in the same repository. A repository may contain as many `internal/` directories as it likes, each drawing its own fence; the compiler cares only about the path prefix of the importer relative to each one. ## What the failure looks like The go command reports it while loading packages, before any type checking: ``` use of internal package github.com/acme/svc/internal/store not allowed ``` There is no flag to switch it off, no build tag that exempts a file, and no way for the importing side to opt in. That is the whole point: the restriction is not negotiable by the consumer, which is what makes it a boundary rather than a suggestion. ## What internal/ does not do - **It does not make names private.** Identifiers in `internal/store` still follow the ordinary export rule — the rest of your tree can only reference names the package exports. `internal/` answers *which packages may import me*; capitalisation answers *which of my names they may then use*. - **It does not hide the source.** The code is still in the repository, still readable, still shown by documentation tooling for anyone browsing the tree. It restricts importing, not reading. - **It does not affect running or linking.** A binary built inside the tree links `internal/` packages exactly like any others. - **It is not about security.** Someone determined to reuse the code can copy it or fork the repository. It prevents accidental coupling, not deliberate copying. ## Why the toolchain bothers In Go, an import path is a public promise. Once another repository imports `github.com/acme/svc/store`, you can no longer rename that package, change its signatures, or delete it without breaking a build you do not control and cannot see — Go gives you no way to enumerate your importers. `internal/` is the mechanism that lets a repository ship a small, deliberate surface while keeping the rest changeable. It is why the standard library itself uses paths like `net/http/internal`: shared implementation code that the standard library's own packages use, and that no program outside it can reach. ## How it is used in practice The common layout is to put everything under `internal/` by default and to move a package out only when there is a real external consumer. A repository that ships several binaries places each one in `cmd/<name>/`, keeps the behaviour in packages under `internal/`, and exports at the top level only the handful of packages other teams are meant to build against. Reviewers then have an easy question to ask of any pull request that adds a top-level package: is this something we are willing to support for other people forever? If not, it belongs under `internal/`. ## Checks you can do in your head Given an import path P containing `internal`, cut P at that element: the prefix before it is the permitted root. If the importing package's own path starts with that prefix, the import compiles; otherwise it does not. Nothing else — not the module, not the repository, not the directory nesting depth — enters the decision.