Move examples back to go-libp2p-examples

[vyzo]

Examples were moved in repo with good intentions, namely keeping them up-to-date.

However this has had very deleterious effects: it requires all prs that pull some dep (pretty much all of them do) to contitnuously babysit examples, and this affects development velocity and developer morale; let alone the diff bloat in every pr.

We propose to move them back where they belong, to their own repo, and add to the release checklist a step that ensures they are kept up to date.

Have cake, eat it too.

[marten-seemann]

I agree, having the examples here is super annoying. Probably half of the CI failures are due to people forgetting to run go mod tidy for all subdirectories (which isn't even a nice command, you'll have to do something like

for x in $(find examples -type d); do pushd $x; go mod tidy; popd; done

The approach taken by IPFS (ipfs/kubo#8516) doesn't work here, as we're using Unified CI and Unified CI doesn't know if a subdirectory is an example directory or not.

So the plan would be:

• resurrect go-libp2p-examples, and update with the current version there
• remove the examples from go-libp2p (paying attention to links set to the example directory in various Markdown files)
• add a release checklist item
• update docs.libp2p.io with the correct link

[marten-seemann]

For reference:

• the issue that the move based on: Test examples in CI #1052
• and the corresponding PR: chore: bring examples back into repository and add tests #1092

[mvdan]

Regarding the diff churn and shell needed to keep modules in sync, I think 1.18's workspaces could help: golang/go#45713

add to the release checklist a step that ensures they are kept up to date.

It's worth noting that such a strategy is less work partially because it offers less guarantees. In particular, the current system will immediately tell you if a change in master, between two releases, breaks examples. #1052 talked briefly about whether we only care about releases or not.

we're using Unified CI and Unified CI doesn't know if a subdirectory is an example directory or not.

Have you considered handling these example modules in a special way? For example:

• Keep them as they are today, but without the replace directive, and targetting the latest root module release
• In CI, add an extra test job or step that, like go-ipfs, replaces the root module with what's currently checked out, runs go mod tidy, and checks that all examples still work

It seems to me like this avoids the pain points (diff churn, manual work) without regressing on the problems we had before (maintain multiple repos, not testing examples between releases, needing to remember to re-test examples at every release).

[aschmahmann]

@marten-seemann can you explain more why the approach taken in go-ipfs won't work with unified CI? Even if unified CI is rubbing against all the modules won't that, in the worst case, just mean we do a little extra testing in CI, such as against the latest release and against the latest master?

[vyzo]

I dont think we really care about examples working against master; we care about examples working with latest release.

…

On Sun, Jan 9, 2022, 17:19 Adin Schmahmann ***@***.***> wrote: @marten-seemann <https://github.com/marten-seemann> can you explain more why the approach taken in go-ipfs won't work with unified CI? Even if unified CI is rubbing against all the modules won't that, in the worst case, just mean we do a little extra testing in CI, such as against the latest release and against the latest master? — Reply to this email directly, view it on GitHub <#1290 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAI4SSCJ52L26QAA3AYEFTUVGRQ5ANCNFSM5LR47HVA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[marten-seemann]

We don't want examples to show how to build with master, because we don't want people to use master.
I want to be able to point people to the examples repo and tell them "do exactly as in the example (incl. the versions used in go.mod)".

In particular, the current system will immediately tell you if a change in master, between two releases, breaks examples.

Examples are not supposed to be tests. If examples uncover a failure that was not covered by a test, this is a good reason to add a new unit test, not to do anything different with the examples.

Regarding the diff churn and shell needed to keep modules in sync, I think 1.18's workspaces could help: golang/go#45713

Without having understood how this works in detail, the current situation is unbearable till we deprecate 1.17 (in 8 months!).

@marten-seemann can you explain more why the approach taken in go-ipfs won't work with unified CI? Even if unified CI is rubbing against all the modules won't that, in the worst case, just mean we do a little extra testing in CI, such as against the latest release and against the latest master?

CircleCI for go-ipfs is running this config: https://github.com/ipfs/go-ipfs/blob/45dac526ea32f4423b395cc55797e91353fca6c1/.circleci/main.yml#L108-L113, just in the examples directory. Unified CI wouldn't know which modules this command should and should not be run in, respectively.

---

In general I'm all for repo consolidation, as it will speed up development. But not this one, this one is slowing us down.
I don't think the examples belong here in the first place. They use pubsub and kad, which are protocols building on top of go-libp2p. There's no plan to consolidate pubsub and kad into this repo.

[aschmahmann]

CircleCI for go-ipfs is running this config: https://github.com/ipfs/go-ipfs/blob/45dac526ea32f4423b395cc55797e91353fca6c1/.circleci/main.yml#L108-L113, just in the examples directory. Unified CI wouldn't know which modules this command should and should not be run in, respectively.

Why does this need to be done as part of the Unified CI when we could just make it a separate workflow? It seems easier to manage than another repo.

We don't want examples to show how to build with master, because we don't want people to use master.
I want to be able to point people to the examples repo and tell them "do exactly as in the example (incl. the versions used in go.mod)".

That's fine, in fact it's even easier. You can just target the module against the latest release and 🎉.

For some background this was the situation in go-ipfs until it was found that the go-ipfs maintainers (perhaps me 😅) were not doing a great job updating the examples on every release so doing it incrementally was easier. So far go-ipfs hasn't gotten many complaints, although to be fair our examples are unfortunately less extensive than the go-libp2p ones.

In general I'm all for repo consolidation, as it will speed up development. But not this one, this one is slowing us down.

I think the approach we're using is slowing us down, but we have at least two other approaches here that could get out of our way. One is just having a separate module in this repo and a workflow for testing it that targets the latest released version. The other is to have a separate module and workflow that tests against the same dependencies present in the latest branch as we currently do in go-ipfs.

I don't think the examples belong here in the first place. They use pubsub and kad, which are protocols building on top of go-libp2p. There's no plan to consolidate pubsub and kad into this repo.

Maybe, and technically you may be right but realistically people's first stop is probably going to be the go-libp2p repo, even the name of the proposed repo is go-libp2p-examples which denotes a connection with this one. It also gives some weight to the stability of go-libp2p-pubsub and go-libp2p-kad-dht to indicate that released versions of go-libp2p will be shortly followed by released versions of go-libp2p-kad-dht and go-libp2p-pubsub compatible with the latest go-libp2p and come with updated examples.

---

Personally I've experienced that relying on checklists when I could've used automation tends to be a burden that results in mistakes and frustration.

However, @marten-seemann and @vyzo are the maintainers doing most of the work on go-libp2p these days so if they are ok with the burden of maintaining an extra repo and updating it soon after go-libp2p releases are tagged then it seems like their call to make. If doing the checklist manually results in the examples lagging behind again I'm sure they'll hear about it in some friendly issues 😄.

[vyzo]

For now we have removed the replace directives, and added to the release checklist, which resolves our immediate pain point while we are working on v0.18.

[marten-seemann]

Thank you for the lively discussion! We've removed the replace directives (as @mvdan suggested), which means that we don't have to update the examples for every commit. It also means that the examples are now more useful (you can just copy-paste them, including go.mod).
I think this is good enough (for now, at least). Technically, they don't belong here, but I can see @aschmahmann's point of this repo being the entry point into go-libp2p.