golang-standards/project-layout

Standard Go Project Layout

Standard Go Project Layout

Translations:

• 한국어 문서
• 简体中文
• 正體中文
• 简体中文 - ???
• Français
• 日本語
• Português
• Español
• Română
• Русский
• Türkçe
• Italiano
• Vietnamese
• Українська
• Indonesian

Overview

This is a basic layout for Go application projects. Note that it's basic in terms of content because it's focusing only on the general layout and not what you have inside. It's also basic because it's very high level and it doesn't go into great details in terms of how you can structure your project even further. For example, it doesn't try to cover the project structure you'd have with something like Clean Architecture.

This is NOT an official standard defined by the core Go dev team. This is a set of common historical and emerging project layout patterns in the Go ecosystem. Some of these patterns are more popular than others. It also has a number of small enhancements along with several supporting directories common to any large enough real world application. Note that the core Go team provides a great set of general guidelines about structuring Go projects and what it means for your project when it's imported and when it's installed. See the Organizing a Go module page in the official Go docs for more details. It includes the internal and cmd directory patterns (described below) and other useful information.

If you are trying to learn Go or if you are building a PoC or a simple project for yourself this project layout is an overkill. Start with something really simple instead (a single main.gofile andgo.mod is more than enough). As your project grows keep in mind that it'll be important to make sure your code is well structured otherwise you'll end up with a messy code with lots of hidden dependencies and global state. When you have more people working on the project you'll need even more structure. That's when it's important to introduce a common way to manage packages/libraries. When you have an open source project or when you know other projects import the code from your project repository that's when it's important to have private (aka internal) packages and code. Clone the repository, keep what you need and delete everything else! Just because it's there it doesn't mean you have to use it all. None of these patterns are used in every single project. Even the vendor pattern is not universal.

With Go 1.14 Go Modules are finally ready for production. Use Go Modules unless you have a specific reason not to use them and if you do then you don’t need to worry about $GOPATH and where you put your project. The basic go.mod file in the repo assumes your project is hosted on GitHub, but it's not a requirement. The module path can be anything though the first module path component should have a dot in its name (the current version of Go doesn't enforce it anymore, but if you are using slightly older versions don't be surprised if your builds fail without it). See Issues 37554 and 32819 if you want to know more about it.

This project layout is intentionally generic and it doesn't try to impose a specific Go package structure.

This is a community effort. Open an issue if you see a new pattern or if you think one of the existing patterns needs to be updated.

If you need help with naming, formatting and style start by running gofmt and staticcheck. The previous standard linter, golint, is now deprecated and not maintained; use of a maintained linter such as staticcheck is recommended. Also make sure to read these Go code style guidelines and recommendations:

• https://talks.golang.org/2014/names.slide
• https://golang.org/doc/effective_go.html#names
• https://blog.golang.org/package-names
• https://github.com/golang/go/wiki/CodeReviewComments
• Style guideline for Go packages (rakyll/JBD)

See Go Project Layout for additional background information.

More about naming and organizing packages as well as other code structure recommendations:

• GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming
• GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.
• GopherCon 2017: Edward Muller - Go Anti-Patterns
• GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps

A Chinese post about Package-Oriented-Design guidelines and Architecture layer

• 面向包的设计和架构分层

Go Directories

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

See the /cmd directory for examples.

/internal

Private application and library code. This is the code you don't want others importing in their applications or libraries. Note that this layout pattern is enforced by the Go compiler itself. See the Go 1.4 release notes for more details. Note that you are not limited to the top level internal directory. You can have more than one internal directory at any level of your project tree.

You can optionally add a bit of extra structure to your internal packages to separate your shared and non-shared internal code. It's not required (especially for smaller projects), but it's nice to have visual clues showing the intended package use. Your actual application code can go 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

Library code that's ok 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 :-) Note that the internal directory is a better way to ensure your private packages are not importable because it's enforced by Go. The /pkg directory is still a good way to explicitly communicate that the code in that directory is safe for use by others. The I'll take pkg over internal blog post by Travis Jeffery provides a good overview of the pkg and internal directories and when it might make sense to use them.

It's also a way to group Go code in one place when your root directory contains lots of non-Go components and directories making it easier to run various Go tools (as mentioned in these talks: Best Practices for Industrial Programming from GopherCon EU 2018, GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps and GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go).

See the /pkg directory if you want to see which popular Go repos use this project layout pattern. This is a common layout pattern, but it's not universally accepted and some in the Go community don't recommend it.

It's ok not to use it if your app project is really small and where an extra level of nesting doesn't add much value (unless you really want to :-)). Think about it when it's getting big enough and your root directory gets pretty busy (especially if you have a lot of non-Go app components).

The pkg directory origins: The old Go source code used to use pkg for its packages and then various Go projects in the community started copying the pattern (see this Brad Fitzpatrick's tweet for more context).

/vendor

Application dependencies (managed manually or by your favorite dependency management tool like the new built-in Go Modules feature). The go mod vendor command will create the /vendor directory for you. Note that you might need to add the -mod=vendor flag to your go build command if you are not using Go 1.14 where it's on by default.

Don't commit your application dependencies if you are building a library.

Note that since 1.13 Go also enabled the module proxy feature (using https://proxy.golang.org as their module proxy server by default). Read more about it here to see if it fits all of your requirements and constraints. If it does, then you won't need the vendor directory at all.

Service Application Directories

/api

OpenAPI/Swagger specs, JSON schema files, protocol definition files.

See the /api directory for examples.

Web Application Directories

/web

Web application specific components: static web assets, server side templates and SPAs.

Common Application Directories

/configs

Configuration file templates or default configs.

Put your confd or consul-template template files here.

/init

System init (systemd, upstart, sysv) and process manager/supervisor (runit, supervisord) configs.

/scripts

Scripts to perform various build, install, analysis, etc operations.

These scripts keep the root level Makefile small and simple (e.g., https://github.com/hashicorp/terraform/blob/main/Makefile).

See the /scripts directory for examples.

/build

Packaging and Continuous 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. Note that some of the CI tools (e.g., Travis CI) are very picky about the location of their config files. Try putting the config files in the /build/ci directory linking them to the location where the CI tools expect them (when possible).

/deployments

IaaS, PaaS, system and container orchestration deployment configurations and templates (docker-compose, kubernetes/helm, terraform). Note that in some repos (especially apps deployed with kubernetes) this directory is called /deploy.

/test

Additional external test apps and test data. Feel free to structure the /test directory anyway you want. For bigger projects it makes sense to have a data subdirectory. For example, you can have /test/data or /test/testdata if you need Go to ignore what's in that directory. Note that Go will also ignore directories or files that begin with "." or "_", so you have more flexibility in terms of how you name your test data directory.

See the /test directory for examples.

Other Directories

/docs

Design and user documents (in addition to your godoc generated documentation).

See the /docs directory for examples.

/tools

Supporting tools for this project. Note that these tools can import code from the /pkg and /internal directories.

See the /tools directory for examples.

/examples

Examples for your applications and/or public libraries.

See the /examples directory for examples.

/third_party

External helper tools, forked code and other 3rd party utilities (e.g., Swagger UI).

/githooks

Git hooks.

/assets

Other assets to go along with your repository (images, logos, etc).

/website

This is the place to put your project's website data if you are not using GitHub pages.

See the /website directory for examples.

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

Don't confuse the project level /src directory with the /src directory Go uses for its workspaces as described in How to Write Go Code. The $GOPATH environment variable points to your (current) workspace (by default it points to $HOME/go on non-windows systems). This workspace includes the top level /pkg, /bin and /src directories. Your actual project ends up being a sub-directory under /src, so if you have the /src directory in your project the project path will look like this: /some/path/to/workspace/src/your_project/src/your_code.go. Note that with Go 1.11 it's possible to have your project outside of your GOPATH, but it still doesn't mean it's a good idea to use this layout pattern.

Badges

• Go Report Card - 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.

  

• GoDoc - It will provide online version of your GoDoc generated documentation. Change the link to point to your project.

  

• Pkg.go.dev - Pkg.go.dev is a new destination for Go discovery & docs. You can create a badge using the badge generation tool.

  

• Release - It will show the latest release number for your project. Change the github link to point to your project.

  

Notes

A more opinionated project template with sample/reusable configs, scripts and code is a WIP.

project-layout's Issues

No , it's not golang-standards

This repo owner confuses beginners (golang-standards), actually its' not a standard. It's just an opinion of a group of coders and historical reasons as it's mentioned in the README and part of the project structure is a bad practice ( like vendor or pkg directories, we have something called mods now!) . I suggest to move this project to another organization called "golang-non-standard" or remove it.

Examples, singular or plural?

The examples folder seems to conflict with: Use singular form for collection repo/folder name. Thoughts?

gRPC ant proto declarations?

What is a common approach when project is using a protobuf and gRPC?

• Where to keep *.proto files?
• Where should be generated files placed, near to protobuf declarations or in another place?
• Any other tips to build clean folder layout when using protobuf and grpc?

Thanks to everyone!

Best project structure when using go 1.11 mod

The first thing you will run into when using go.mod, putting code outside GOPATH, and using the recommended folder structure is that your cmd/ does not have access to your internal or pkg folder. Therefore you are automatically required to resort to using the require/replace fix to actually get access to the code or actually split your code into actual modules and upload separately.

While the require/replace fix works and builds, your IDE will probably still have problems picking up the imports for good code navigation unless you manually update your go.mod file in the pkg or internal folder. (you cant use go build to update your go.mod/sum file as there is nothing to build in the folder) Of course, this is more of an IDE problem.

module some-api

replace some-pkg v0.0.0 => ../../pkg

require (
	some-pkg v0.0.0
)

Would people still recommend this folder layout when using go modules, have multiple cmd applications, and especially when putting code outside the gopath? I am curious as I see more and more people starting to use modules and putting their code in a GOPATH-less environment and this is for sure bound to create problems and confusion when using modules as it requires "some" custom setup. Of course, nothing major once you figure it out.

Come to think of it, this is more of a general issue with go mod. You will run into this issue from the moment you put your main.go file in a subfolder and not the root.

golang.org says to use a src/ directory

Your comments on the use of a src/ directory aren't correct, at least in the GOPATH approach which has been the recommendation in the past:
https://golang.org/doc/gopath_code.html

Here's what happens if you don't have a src/ directory in your project:

lctl.go:3:8: cannot find package "lctlutil" in any of:
/home/dean/bin/go1.14.linux-amd64/go/src/lctlutil (from $GOROOT)
/home/dean/src/golang/integration/lctl/src/lctlutil (from $GOPATH)
/home/dean/src/golang/go3p/src/lctlutil

Go looks for a src/ directory.

Also the link in that section points to an updated page which doesn't mention the src/ directory. Apparently it has been updated for modules.

[Question] Working with internal folder with a go module

I've always been a big fan of go and this is my first time trying to follow a suggested structure for my project instead of just making it up.

I was trying to use the internal/app/_your_app_ structure with a go module. To achieve this I had to add the below to my go.mod file and had to add a go.mod file to the relative folder, as I wanted to import as "github.com/sc7639/network-cli-tool/internal/app/command".

require github.com/sc7639/network-cli-tool/internal/app v0.0.0

replace github.com/sc7639/network-cli-tool/internal/app => ./internal/app/network-cli/

I'm just wondering if this is how you would suggest doing it or if there is a better way I'm seeing?
Thanks in advance for any help.

[Question] Where to store .ddl files

Hi, I was wondering, where would you store .ddl files? In /configs? In the same directory as the go database code that uses it?

pkg directory should not be recommended for use

The general consensus of the Go community has been converging on the idea that the pkg/ directory is a useless abstraction / indirection. Instead, people are encouraged to either put the packages in the top-level of the repository, or to create a repository structure that structures things based on their primary functionality of domain in the business logic.

So while in your example you may encourage people to have the following layout:

pkg/
  server/
    handlers/
  poller/
    config/
    manager/

We instead would prefer:

server/
  handlers/
poller/
  config/
  manager/

This may seem innocuous, but because this project has asserted itself as some sort of Go standards body what is being recommended here is being taken seriously. In the Slack workspace, where there are over 30k registered users, we quite often need to correct people who are using pkg/ and have them ignore the recommendations here. Some of the things recommended here are good, and I'd like to be able to use them as a resource. That said, considering the current pkg/ recommendation we're hard-pressed to use this as a resource because we have to tell people to ignore certain parts.

Add readme chinese translation

Add readme chinese translation.

As shown below.

Standard Go Project Layout

🌍 English ∙ 简体中文

This is a basic layout for Go application projects. It's not an official standard defined by the core Go dev team; however, it is a set of common historical and emerging project layout patterns in the Go ecosystem. Some of these patterns are more popular than others. It also has a number of small enhancements along with several supporting directories common to any large enough real world application.

---

Go项目标准布局

🌍 English ∙ 简体中文

这是Go应用程序项目的基础布局。这不是Go核心开发团队定义的官方标准；无论是在经典项目还是在新兴的项目中，这都是Go生态系统中一组常见的项目布局模式。这其中有一些模式比另外的一些更受欢迎。它通过几个支撑目录为任何足够大规模的实际应用程序提供一些增强功能。

del

del

void

Dockerfile for standard project layout

Does anyone have sample of dockerfile for standard project layout for the multi stage build ?

please help

test/.dir or test/_dir are not ignored by Go

The directories starting with . or _ are not ignored by Go. At least I tried importing exported symbols from those packages and it totally works and builds

Not sure what do you mean by the phrase:

Note that Go will also ignore directories or files that begin with "." or "_", so you have more flexibility in terms of how you name your test data directory

Internal app/pkg Directory Clarification

I was wondering what the internal/app directory was for, exactly. The README.md says:

Put your actual application code in the /internal/app directory

What does it mean by your "actual application code"? I thought that application code goes in the /cmd/<app_name>/ directory. And if it's not part of the main package, shouldn't it then, by definition, be a package that belongs in either /pkg/ or /internal/pkg/?

I've been placing internal packages directly in the /internal/ directory, and it's been working out well. I know this repo is simply a suggestion, and I might continue to do what I've been doing, but it would be awesome if you could explain to me why you chose the way that the docs suggest, as it might be better than my way for reasons I don't yet know. Thanks!

Where to put "web" assets like .css, .scss/.sass, .less to build, minify and copy to "web/static"

Where to put "web" assets like .css, .scss/.sass, .less that need build, minify and copy to "web/static"?

Missing simple approach to building and vendoring

Pulling out my hair to do something as simple (or in go- complex) as using dep, gb and make to perform a simple build of a repo with this structure. Even if its opinionated it would help to show

• a Makefile including gb (the refs are good but much too complex for a beginner)
• a way to use dep for installing dependencies as part of the make process

Add Traditional Chinese version

I'd like to contribute a Traditional Chinese (zh-TW) version of the README.

Proposal: It would be nice if there's a CLI to generate this layout

Not clear where to put files containing secrets

I've a service account file generated by Google which contains (secret) keys. I can't conclude from the current setup where to put these into.

My first idea was configs. But for me, configs can be public.

A lib (meaning /pkg) where we're forced to return a Version (considered /internal)

Generally I'm still unsure about pkg, but lets keep that there #10. It still applies that you need your lib for external use must be independent from internal stuff.

Assuming I'd like to follow the current project-layout consensus, especially /pkg and /internal:
I have a lib implementing this requiring the implementer to return its app's current version here.

Now, the app's current version lays perfectly somewhere in /internal and I really like not to have an include into /internal.

1. I could define a version string parameter, Version field in a struct or SetVersion(version string) method and such. That approach looks messy, as I probably would have to carry that option multiple "layers", but the caller has ultimate choice. But I don't like the option at all, that the caller has to set a version...
2. I could also see, that the resulting version is indeed dependent from my lib (code-wise), but the meaning of that field is definitely practical (should return the version of the binary running - so not the "lib-version")
3. It could depend on the "caller/user" to either want 1. or 2. (= variant 1, or set it with help of 2. with the package variable).
4. But this package variable is set on build-time with -ldflags, so someone importing that code will never get the real version.

Your thoughts from your angle?

Go project sturcture question

Hi,

I've created this question https://stackoverflow.com/questions/47788850/go-project-structure-best-practise in stack overflow and I wonder if the repo author can give is insight.

Thanks,
Sofia

I wrote a script to initialize the project, please check it!

`#!/bin/bash

PWD=$(pwd)
cd $PWD

if [[ "$1" = "" ]]; then
echo -ne "Please Input The Golang Porject Name: "
read project
if [ "$project" = "" ]; then
echo -e "demo";
PRO_NAME=demo;
else
PRO_NAME=$project;
fi
else
PRO_NAME=$1;
fi
#build directory
echo "Init $PRO_NAME Directory …"
mkdir -p $PRO_NAME/api
mkdir -p $PRO_NAME/assets
mkdir -p $PRO_NAME/build
mkdir -p $PRO_NAME/cmd
mkdir -p $PRO_NAME/conf
mkdir -p $PRO_NAME/deployments
mkdir -p $PRO_NAME/docs
mkdir -p $PRO_NAME/examples
mkdir -p $PRO_NAME/githooks
mkdir -p $PRO_NAME/init
mkdir -p $PRO_NAME/internal
mkdir -p $PRO_NAME/pkg
mkdir -p $PRO_NAME/scripts
mkdir -p $PRO_NAME/test
mkdir -p $PRO_NAME/third_patry
mkdir -p $PRO_NAME/tools
mkdir -p $PRO_NAME/vendor
mkdir -p $PRO_NAME/web
mkdir -p $PRO_NAME/website
cd $PRO_NAME
touch .gitkeep
go mod init $PRO_NAME

echo "Generate main.go "
cd cmd
echo "package main" > main.go
echo >> main.go
echo "import (" >> main.go
echo " \"fmt\"" >> main.go
echo ")" >> main.go
echo >> main.go
echo "func main() {" >> main.go
echo " fmt.Println(\"Hello $PRO_NAME!\")" >> main.go
echo "}" >> main.go
gofmt main.go
echo "Init $PRO_NAME Success!"`

Where should the generated Log and similar files be stored?

Where should the generated Log and similar files be stored?

Named a storage floader in the root directory?

Best practice for file server path name? /files or /static or what else?

Is there a best practice in GO for file server path name?

I can imagine "/files" or "/static".

What do you think?

We are following Golang standards project layout, can we be added to the examples?

Hello,

As the title said, here is the address: https://github.com/godiscourse/godiscourse

Thanks

Why "web/template" (singular) instead of "web/templates" (plural)?

Why "web/template" (singular) instead of "web/templates" (plural)?

What about mail templates, localization files and sql files (migrations)?

Hi, guys!

Thanks for repo, it's useful.
But I confused about a place of templates, localization files, sql files in the project structure. What do you think about that?

What is the best project structure for a multi language monorepo?

I am building a microservices project with services written in Go, Python and JavaScript for the frontend, what is the best way to structure a multi language monorepo?

where put paths and router to make an API

where put paths and router to make an API in this arquitecture

.go files generated from swagger.yml

What is a common approach when building API Server from swagger spec file (usually swagger.yml).
Command swagger generate server... generates a bunch of .go files. Where those generated .go files should be placed.
Is a good approach to put them to /pkg/api/ ?

This repository has multiple serious issues

The existence of this repository is harmful for Go beginners. People arrive here from Google searches, looking for ways to structure their small, simple packages. What they find is overwhelming, at the least.

It has several serious issues:

1. No go.mod file, while modules are becoming a standard for Go dependency management
2. Suggests to place all exportable code in pkg/, which is outdated advice and no longer recommended for Go projects (as it adds a superfluous path component to every import).
3. Has a large number of directories, most of which aren't needed by 99% of projects

Please either spend some time to modernize this project, or delete it

Include buildable library and command example code

Thanks for showing how to name the directories. I also need to know how to:

1. Add library code
2. Import library code into a binary
3. Build a binary
4. Perform offline builds

How about adding some example code? Ideally, this would be a complete buildable repository with short .go files and Makefile that show best practices for building, running tests, linting, etc.

It would be great to incorporate the solution for golang/go#37554 , to save folks from having to understand 27 pages of technical discussion.

These things are not at all obvious. For example, the obvious command go build ... does not produce any binaries. Running go build -v ... produces no output and go build -vvv ... doesn't work. And if I manage to produce a binary with go build cmd/example/example.go, the corresponding go clean does not delete it. Please put the appropriate commands in Makefile.

Here's example code to get started:

// go.mod
// Allow others to import this module into their projects or use `go install`:
module github.com/org1/example
// For private code:
//module _/example

go 1.14

// lib1/lib1.go
package lib1

import "fmt"

func Func1() {
	fmt.Println("lib1.Func1()")
}

// pkg/lib2/lib2.go
package lib2

import "fmt"

func Func2() {
	fmt.Println("lib2.Func2()")
}

// cmd/example/example.go
package main

import (
	"github.com/org1/example/lib1"
	"github.com/org1/example/pkg/lib2"
	// "_/example/lib1"
	// "_/example/pkg/lib2"
)

func main() {
	lib1.Func1()
	lib2.Func2()
}

# Makefile
#GOCACHE=output/cache/ fails with "GOCACHE is not an absolute path"
GO_BUILD=go build -pkgdir output/pkg/ -i -o output/ -v -trimpath
buid: mkoutput
	${GO_BUILD} ./...

mkoutput:
	mkdir -p output/ output/pkg/

clean:
	rm -rf output/

$ make
mkdir -p output/ output/pkg/
go build -pkgdir output/pkg/ -i -o output/ -v -trimpath ./...
runtime/internal/sys
math/bits
internal/race
unicode/utf8
unicode
runtime/internal/atomic
internal/cpu
sync/atomic
runtime/internal/math
internal/testlog
internal/bytealg
math
runtime
internal/reflectlite
sync
errors
sort
internal/oserror
io
strconv
syscall
reflect
internal/syscall/execenv
internal/syscall/unix
time
internal/poll
os
internal/fmtsort
fmt
github.com/org1/example/lib1
github.com/org1/example/pkg/lib2
github.com/org1/example/cmd/example
$ ls -alF output/
total 4240
drwxr-xr-x   4 user  staff      128 Jul  9 17:03 ./
drwxr-xr-x   8 user  staff      256 Jul  9 17:03 ../
-rwxr-xr-x   1 user  staff  2170120 Jul  9 17:03 example*
drwxr-xr-x  20 user  staff      640 Jul  9 17:03 pkg/
$ ./output/example 
lib1.Func1()
lib2.Func2()
$ make clean
rm -rf output/
$

Edit: Added alternative _/example module name. Ran go clean -cache and now build command shows output.

Project not found in godoc

Hello,

It seems godoc can't find this project. My best guess is because there's no go files in this project. However, I'm getting the same behavior in a project of mine which has go files, just not in root directory. You can see by the broken badges in README.md. Any suggestions regarding the best way to solve this? Rethink this aspect of the project structure or check with the guys in godoc to see what can be done over there?

Google App Engine deployment

What would be the approach to deploy the cmd/<name>/main.go structure to Google App Engine?

The regular command gcloud app deploy --project=<whatever> won't pick up that the main file is in another folder, and the entry file cannot be specified to the command.

I suppose the only hack-around would be to put the main.go in the base directory for deployment purposes? Feels dirty.

What about "testdata"

It seems common to have a "testdata" directory for additional test data. Any specific reason why it's not included in this repo?

Delete this repo

Please, delete this repo, because it brings nothing else but confusion and encourages bad practices in go (a lot around naming) especially for beginners.

Especially it's bad when new go developers start to advocate bad practices and use this repo as a reference.

Instead, create a list of resources that would bring knowledge about the "industry standards" (the way how go is written in stdlib)

Like those:

0. Go basics

https://tour.golang.org/welcome/1
https://gobyexample.com/
https://blog.golang.org/context
https://ekocaman.com/go-context-c44d681da2e8

Would highly recommend to read this even if you’re advanced Gopher - http://devs.cloudimmunity.com/gotchas-and-common-mistakes-in-go-golang/

1. Style guideline for Go packages

https://rakyll.org/style-packages/

One of the famous figures and main contributors to Go language, Rakyll, writes about importance of naming and structuring of the packages.

2. Effective Go

https://golang.org/doc/effective_go.html

Effective Go article is a community evangel of how effective Go code should be written.

3. Code Review Comments

https://github.com/golang/go/wiki/CodeReviewComments

Wiki page from Go repository with idiomatic code habits that would help you to avoid traps of trying to write Java (or C#, or TypeScript, or Javascript) in Go which never works.

4. Structuring applications for Growth in Go

https://www.youtube.com/watch?v=LMSbsW1Xpwg
In this lightning talk, Ben Johnson gives a quick idea of what kind of issues you might face with inappropriate project structure

5. Best Practices for Industrial Programming

https://www.youtube.com/watch?v=PTE4VJIdHPg
Peter Bourgon dives deeper into the ways of setting up the project structure that are more adopted within the industry, providing also more justifications on an issues that he was facing on his Go journey. A lot of his practices are widely used within the Go community.

underscoring /web and /website folders (not containing Go source code)

When using "Standard Go Project Layout" I face serious issue with /web directory, which in my case contains really big frontend project. I'm working with yarn workspaces in that folder, so when I run for instance go mod tidy command I'm getting the following warnings:

warning: ignoring symlink /home/sysadmin/Documents/<project>/web/node_modules/<some package>

Also I'm not sure if scanning entire /web folder for anything related to Go is very effecient.
So one possible solution is to rename /web to /_web.

P.S. running go help packages we get the following:

...
Directory and file names that begin with "." or "_" are ignored
by the go tool, as are directories named "testdata".

References for anti-recomendation

This is a common layout pattern, but it's not universally accepted and some in the Go community don't recommend it.

In the /pkg section; either state the pros/cons or link to something that expounds

What happens if I put the frontend (SPA) inside the Web directory ?

What happens if I put the frontend (SPA) inside the Web directory once I need to deploy ?

I mean, I use CI to build let's say three Docker containers, reprsenting my three microservices. With Cobra.

They are called mysoftware-collector and mysoftware-pusher and mysoftware-server.

And on another Git repository, I develop the mysoftware-frontend with Angular.

If I use the /web for the frontend Angular files. How do I deploy it ?

Thanks !

Set this project as repository template

Thank you for this project. GitHub has just shipped a new feature that allows to mark a repository as a template for new repositories. Setting it up should take just a minute, but it's not something other developers can do via Pull Requests: it requires admin privileges.

Here's how to do it: https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/

[Question]Which directory is appropriate for cgo dependency?

hi,
where to store cgo files? such as .h .so?

where are go.mod and go.sum files

Hello,

I'm new to go and have what I think is an extremely basic question: Where are the go.mod and go.sum file or files? Edit: and a follow on question, can you provide some example of go.mod files?

Thanks

Go Modules is fully enabled/official right now, can we have the update in this project layout?

How in the hell do you use go modules with a complex app with multiple directories.

Every document or blog I have found are merely some simple helloworld crap with a single directory of source files and no external libraries.

I'm trying to convert my k8s controller to using go modules because getting our CI/CD system to work with dep is an ungodly nightmare.

Is there a good doc or example of someone using go modules with a complex directory structure of many go packages at multiple levels?

What a hair-pulling nightmare go dependencies are.

src directory

Go language documentation itself suggested to use the src directory. Why did you mention in your README that src should not be used.

https://golang.org/doc/code.html

Want to add a Japanese version

If I want to add the Japanese version, should I add a file like README_ja.md ?

Also, when reviewing, I plan to have some Japanese people look at it.

Rename the organization

The name organization name golang-standards is misleading for beginners and people new to Go. It implies that the included repositories - which are misleading as well, btw - conclude official standards, which is definitly not the case.

How to use this layout for a gRPC API Microservice Project?

It would be really helpful if you can give an example on how to use this layout for gRPC based microservice systems, since gRPC and Microservices are quiet common now a days.

No src folder although the official guide tells to?

Hey,

I was wonderin what you think about the official Go documentation, which recommends creating a src folder, whereas you tell us not to.

Here's the link: https://golang.org/doc/code.html

Lack of reasoning behind suggestions

Happy to see this attempt, but none of the decisions or suggestions are explained.

If there are valid reasons to use such a structure, it should be easy to list those reasons.

As someone who has my own preferred structure, I would need some reasons to switch. "Unifying everyone's structure" is a great argument for a unified structure, but not necessarily this structure.