Added pkg directory to host importable packages

[owais]

Added a new pkg sub-directory that hosts code intended to be imported by
3rd party packages.

Packages with internal in their import path cannot be imported by
other Go programs. This is enforced by the compiler. Some of the code
currently hosted by the internal director needs to be made available to
other programs so additional exporters, receivers and processors can be
easily implemented independently.

As an alternative to /pkg we can also move them to project root but a lot of packages there might add clutter. I'm fine with either approach.

[codecov-io]

Codecov Report

Merging #69 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #69   +/-   ##
=======================================
  Coverage   71.37%   71.37%           
=======================================
  Files          91       91           
  Lines        6022     6022           
=======================================
  Hits         4298     4298           
  Misses       1500     1500           
  Partials      224      224

Impacted Files	Coverage Δ
cmd/occollector/app/builder/receivers_builder.go	85.18% <ø> (ø)	⬆️
cmd/occollector/app/builder/exporters_builder.go	92.64% <ø> (ø)	⬆️
pkg/configv2/configv2.go	98.64% <ø> (ø)
processor/addattributesprocessor/factory.go	100% <ø> (ø)	⬆️
receiver/jaegerreceiver/factory.go	100% <ø> (ø)	⬆️
pkg/configv2/test_helpers.go	50% <ø> (ø)
receiver/prometheusreceiver/factory.go	72.09% <ø> (ø)	⬆️
cmd/occollector/app/collector/collector.go	79.26% <ø> (ø)	⬆️
pkg/configmodels/configmodels.go	0% <ø> (ø)
exporter/opencensusexporter/factory.go	87.32% <ø> (ø)	⬆️
... and 8 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update cb2f08b...ffe6d64. Read the comment docs.

[tigrannajaryan]

LGTM

[songy23]

Please rebase.

[flands]

LGTM

[owais]

@songy23 done, thanks.

[bogdandrutu]

I think there was a long conversation about using pkg. And we decided to not do that.

[tigrannajaryan]

@bogdandrutu can you please point to the discussion or if you remember the arguments post here?

[bogdandrutu]

census-instrumentation/opencensus-service#430

[tigrannajaryan]

@owais I tend to agree with some of the arguments against pkg. It looks superfluous to me and unnecessarily lengthens import path. With internal being the convention for stuff that is not for external use I think "every else is public" is not a bad rule.

I do not see much benefits in pkg provided that the public packages are properly and clearly organized. Perhaps this effort is better spent in cleaning up the package structure that we have, I think it could use some improvement.

I'd like to know what you think about this.

We probably need a broader discussion about code organization. I think the codebase could generally benefit from better organization (something along the clean architecture lines: https://medium.com/@eminetto/clean-architecture-using-golang-b63587aa5e3f - so a layered organization with one clear direction of dependencies).

[owais]

I don't have any strong preference for pkg. I thought it shows clear intent that the code inside is meant to be consumed by other projects. Totally fine if we want to invert that by treating internal as strictly private and everything else (probably except cmd) as public.

[bogdandrutu]

If you need the code to be "public" put it in a directory directly in the root project not in internal.

[tigrannajaryan]

My understanding is that internal is enforced by the compiler. You cannot import it from a code that is in a different tree. So you don't just treat it as private it is enforced to be private.

It then leaves everything else to be public. Even cmd I think is fine. If you have stuff that is exportable from cmd package I do not see a reason why it should not be possible (or be prohibited by convention) to import.

[owais]

I'll move it all outside but have a question about the config packages. We could move the config packages to the project root or we could create a config package at root and host configmodels and configv2 inside it. So the structure would look like:

- config
    - v2
    - models

I like that everything related to config will be inside the config "container".

I don't like that the import path lies about the package name. I mean when importing opentelemetry-service/config/v2, the package would still be accessible in code with configv2 which can be a bit surprising. We could change the package identifier to v2 but that would make code importing the package more cryptic as it wouldn't be obvious what v2 is when reading the code.

Option 1.

- factories
- config
     - v2         // imported as configv2
     - models     // imported as configmodels

Option 2.

- factories
- configv2 
- configmodels

Interested in hearing what everyone thinks.

[tigrannajaryan]

I would move all models to a separate package. Granted, we currently have only config models but there can be more. I find that it is reasonable that models are a separate package. They are the glue that holds other packages together and they should be importable from any other package. At the same time other package should be more careful about importing each other.

So I would do this:

- cmd
- models (config models are here)
- factory (this can be split into 3 parts and go into the corresponding packages)
- configv2 (should be later renamed to config when cleaning up, maybe even now is the time)
- exporter
- receiver
- processor
- internal

[owais]

Moved out of pkg #73