search

mesos / mesos-go

Go language bindings for Apache Mesos
Apache License 2.0
545 stars 146 forks source link

Split examples from library #289

Open pires opened 7 years ago

pires commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 notifications@github.com 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 https://github.com/mesos/mesos-go/issues/289#issuecomment-295435594, or mute the thread https://github.com/notifications/unsubscribe-auth/ACPVLKQI5AicvPYtKVas7IAloqGRD4W1ks5rxnNZgaJpZM4NCNaU .

pires commented 7 years ago

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 commented 7 years ago

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

jdef commented 7 years ago

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 commented 7 years ago

I can second that.

jdef commented 7 years ago

skeleton docs in #292