Code Organization - Githubissues

abhinav commented 7 years ago

Currently we put executables under top-level directories and re-usable library code under lib/. We should perhaps put library code at the top level and commands under a cmd/ directory.

So we would have,

uber-go/tools
  |- cmd/
      |- update-license/main.go
      |- parallel-exec/main.go
  |- parallel/
      // package parallel

This is similar to how golang.org/x/tools is organized.

Also we'll want to make it clear that there are no API stability guarantees to the library code. It's for use by other commands in this repo only.

abhinav commented 7 years ago

@prashantv @peter-edge Thoughts?

abhinav commented 7 years ago

Created #6 while we discuss this

prashantv commented 7 years ago

Do we never want anyone outside of this repo to rely on the library code? If so, perhaps we should just put all library code in internal, and have tools at the top level?

abhinav commented 7 years ago

My understanding of this repository was that it was strictly for tooling. As such, it will always be used via go get, pulling master at all times. Tagging versions wouldn't serve any purpose, and without that users cannot safely consume the library components of this repository. I still think it's preferable (but not required) for the library components to be usable from outside.

The options I think we have are,

Tag version numbers, versioning on both, library and executable changes. This unfortunately means that the version number applies to all the tools.
Tag nothing and follow a best-effort approach to maintaining backwards compatibility in the library components. Users of the library components would use them with the understanding that the APIs may break at anytime, so they should pin to specific hashes.
Tag nothing and put library code in internal/. This would solve most of the problems here but I dislike that we won't be able to use the library components from outside. If you feel strongly about versioning the library components, this may be the only approach.

prashantv commented 7 years ago

Do we have any usecases for consuming the library code outside of this package? If not, I'd vote for the third option. If we find that the library is more useful, we should move it to a separate repo in uber-go.

abhinav commented 7 years ago

@prashantv, okay I can buy that. Plus that'll lead to zero breakage to existing users since the executable paths won't change.

@peter-edge?

uber-go / tools

Code Organization #5