Rename example directory to _examples

[rhcarvalho]

Quoting @kataras from https://github.com/getsentry/sentry-go/pull/78#issue-339696824:

Recommendation

Please rename your ./example directory to ./_examples and use a different go.mod and go.sum files for each of the web frameworks provided there, this way your library will not depend on unnecessary third-parties as _ prefix can be go-skipped.

Thanks, Gerasimos Maropoulos. Author of the Iris Web Framework.

[rhcarvalho]

The recommendation has two parts:

1. Rename ./example/ -> ./_examples/
2. Add individual go.mod + go.sum files under ./_examples/*/ creating new "submodules"

Wanted to note that (1) can be done independent of (2), and each change has certain impact.

---

For (1), apart from the rename itself we'd need to update official links that point to the old location, and live with the fact that some links will be broken. On the plus side, the go tool will ignore anything under _examples when working on the top level of the repository :+1:

---

For (2), having two or more modules in the same repo is not without its trade-offs. See discussion in https://github.com/golang/go/issues/27056, in particular the experience reports in https://github.com/golang/go/issues/27056#issuecomment-419336256 and https://github.com/golang/go/issues/27056#issuecomment-436841841.

There is some extra work to maintain cross references between modules and it might eventually bring some pollution to Git tags since the modules are versioned independently.

For "example code" this may be okay.

@kataras what's your experience with that? I see that https://github.com/kataras/iris has examples under _examples, but they do not have their own go.mod files.

---

Note that if the problem statement is "Remove example code from the main sentry-go package", an alternative solution is to move the examples to a separate repository (also with its considerations with regards to maintenance, etc).

[kamilogorek]

@rhcarvalho I reverted all my changes so we are back to green with a new 0.3.1 release. Let's discuss these 2 things next week :)

[kataras]

Hello @kamilogorek , @rhcarvalho,

Based on my experience, examples should be located at _examples and each one of the example should contain go.mod and go.sum files separately. Other subpackages should NOT contain go.mod files because it will produce go module errors on build.

If you want to keep supporting older versions of Go but at the same time be able to offer new capabilities based on go1.13 then create new files with updated code (such as the new github.com/kataras/iris/v12) and tag those files with // +build go1.13 (they use the new errors.Is/As and fmt.Errorf(%w) methods). Older versions of that file should be tagged with // +build go1.11 or go1.9 (like the iris v11 you had previously).

If you need any help I could start preparing a PR with all the above proposals applied on it.

Thanks, Gerasimos Maropoulos. Author of the Iris Web Framework

[kamilogorek]

Thanks for the feedback @kataras!

[rhcarvalho]

Multi-module repository FAQ: https://github.com/golang/go/wiki/Modules#faqs--multi-module-repositories

Should I have multiple modules in a single repository? Adding modules, removing modules, and versioning modules in such a configuration require considerable care and deliberation, so it is almost always easier and simpler to manage a single-module repository rather than multiple modules in an existing repository.

[rhcarvalho]

https://github.com/golang/go/wiki/Modules#can-an-additional-gomod-exclude-unnecessary-content-do-modules-have-the-equivalent-of-a-gitignore-file

Can an additional go.mod exclude unnecessary content? Do modules have the equivalent of a .gitignore file?

One additional use case for having multiple go.mod files in a single repository is if the repository has files that should be pruned from a module. For example, a repository might have very large files that are not needed for the Go module, or a multi-language repository might have many non-Go files.

An empty go.mod in a directory will cause that directory and all of its subdirectories to be excluded from the top-level Go module.

If the excluded directory does not contain any .go files, no additional steps are needed beyond placing the empty go.mod file. If the excluded directory does contain .go files, please first carefully review the other FAQs in this multi-module repository section.