Split examples from library

[pires]

Mixing library code and dependencies with examples seems a little messy and actually limits adopting dependency management solutions like glide (see #283). Therefore, I suggest moving examples to a new repo, i.e. mesos-go-examples.

[pires]

It's actually breaking godoc usage for v1 as one must navigate to https://godoc.org/github.com/mesos/mesos-go/api/v1/lib to actually see the documentation.

[jdef]

v0 and v1 are both kept in the same repo to allow for easier migration from the old to the new APIs. how would splitting examples impact godoc breakage?

…

On Wed, Apr 19, 2017 at 4:49 PM, Paulo Pires ***@***.***> wrote: It's actually breaking godoc usage for v1 as one must navigate to https://godoc.org/github.com/mesos/mesos-go/api/v1/lib to actually see the documentation. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#289 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACPVLKQI5AicvPYtKVas7IAloqGRD4W1ks5rxnNZgaJpZM4NCNaU> .

[pires]

I'm not arguing v0 and v1 should be split. I'm arguing examples could move to a separate repo.

Now, the fact v1 code is in folder api/v1/lib makes godoc unable to render the doc unless you explicitly navigate to the api/v1/lib. If examples were to move elsewhere, you wouldn't need the lib folder.

[pires]

Try https://godoc.org/github.com/mesos/mesos-go/api/v0.
Now, try https://godoc.org/github.com/mesos/mesos-go/api/v1.

[jdef]

Thought about this proposal some more. I think there's real value in keeping the examples and the library code in the same repo. Maybe the "nature" of the examples should change. For example, they could be repackaged in the form of automated e2e tests.

Your point about "messy" dependencies is noted. However, even if the examples are refactored into automated e2e tests that doesn't solve the dependency issue.

The fact that godoc users need to "click through" to the lib package to see the API types doesn't bother me at all. To reduce the "surprise" factor for this, we could add a doc.go file to the api/v1 package to add commentary that directs users to the appropriate subpackage (and provides example library usage).

[pires]

I can second that.

[jdef]

skeleton docs in #292