Code Organization

[abhinav]

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]

@prashantv @peter-edge Thoughts?

[abhinav]

Created #6 while we discuss this

[prashantv]

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]

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]

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]

@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?