Repo directory structure

[bill3tt]

What is the desired directory structure of the repo?

Assuming that the aim is to make the project it as easy as possible to understand, and allow people to find the things they want quickly, I propose the following principles:

• Clear delineation of example code from application code.
• Top level directory reserved only for necessary files (go.mod, README.md) etc.
• All tool source files and directories in the same directory.
• All examples must live in their own directory

Given these parameters, something like the following would work:

gocodeit/
├── LICENSE
├── Makefile
├── README.md
├── examples/
│   ├── infra-my-mon/
│   └── prom-remote-read-bench/
├── go.mod
├── go.sum
└── src/
    ├── abstractions/
    ├── encoding/
    ├── files.go
    ├── gen.go
    ├── panic.go
    └── providers/

Question - is it ok to use src to hold the source code - or does this have a special reserved meaning in Golang that we should not overload?

Happy to do the refactor if you guys give me a hell yeah

[domgreen]

not sure about moving the code under src as this is currently a library so we should keep them all at the top level.
Agree with the example change however ... I see this along with abstarctions / encoding being pulled out of this repo at some point if the project gains momentum.

[domgreen]

The standard project layouts for go code is here https://github.com/golang-standards/project-layout

[domgreen]

Oh no https://github.com/golang-standards/project-layout#directories-you-shouldnt-have

[domgreen]

I could see the following though:

newname/
├── LICENSE
├── Makefile
├── README.md
├── docs/
│   ├── docterstrange.md
├── examples/
│   ├── infra-my-mon/
│   └── prom-remote-read-bench/
├── go.mod
├── go.sum
├── files.go
├── gen.go
├── panic.go
├── doc.go 
└── pkg/
    ├── abstractions/
    ├── encoding/
    └── providers/

[bill3tt]

Definitely looks better than we have already 👍 - let's try and be as consistent with the community advice as possible.

The only other thing is:
internal/

Private application and library code. This is the code you don't want others importing in their applications or libraries.

With that in mind - what about:

gocodeit
├── LICENSE
├── Makefile
├── README.md
├── examples
│   ├── infra-my-mon
│   └── prom-remote-read-bench
├── go.mod
├── go.sum
├── internal
│   ├── encoding
│   ├── files.go
│   └── panic.go
└── pkg
    ├── abstractions
    ├── gen.go
    └── providers

Any code that might be imported and used must live in /pkg. Any code not intended to be used by users should live in /internal. As per the guidance @domgreen linked.

[domgreen]

• is encoding/files actually internal... surely users will want to use the encodings?
• would gen.go not need to go inside a pkg otherwise the improt would be name/pkg

[bill3tt]

is encoding/files actually internal... surely users will want to use the encodings?

This obviously depends on the desired surface area of the API. My thought was that users would just call Generate with their structs. The secret-sauce of this tool is the encodings between structs and output config, and IMO users do need to see or care about that.

would gen.go not need to go inside a pkg otherwise the improt would be name/pkg

Yeah I think so - that's what I included in the above example.

[domgreen]

Interesting, this is not how the package is currently designed generate basically loops over the "files" that have already been added to write them to disk ... it is currently up to the user to call encoding.xxx

	gci.With("config").Add(name+".yaml", encoding.GhodssYAML(set))

I think having encodings public and usable will encourage ppl to add and experiment with their own encodings.

With regard to gen i think an import path like import "github.com/bwplotka/gocodeit/pkg" wouldnt be nice to consume.

[bwplotka]

So for me mimics is a library mostly. So I would be fine with just storing the old gci (now mimics) in the root location. Also I cannot see anything that would be need to create internal. Some day it might be the case not now.

With regard to gen i think an import path like import "github.com/bwplotka/gocodeit/pkg" wouldnt be nice to consume.

Exactly.
That's why making it as short as possible make more sense: github.com/bwplotka/mimic

[bwplotka]

I would say the current structure is OK, what exactly we should change?

[bwplotka]

BTW there is no rule packages has to be in pkg

[domgreen]

I agree, its a package so would leave it as is.