Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

go needs a way to mark example code #30596

Closed
nim-nim opened this issue Mar 5, 2019 · 7 comments
Closed

go needs a way to mark example code #30596

nim-nim opened this issue Mar 5, 2019 · 7 comments

Comments

@nim-nim
Copy link

nim-nim commented Mar 5, 2019

go version go1.11 linux/amd64

Many Go projects bundle example code.

Quite often, this code is incomplete (with to-be-filled sections), stale (not working anymore without fixes) or adds extensive build deps (deps that are specific to the example and not needed to use the production part of the project).

This kind of example code needs to be filtered in unit tests and dep downloads, otherwise BAD THINGS will happen (failing builds, lots of unnecessary downloads, or even downstream starting to depend on example code when the upstream never intended to maintain it at production quality).

go needs a way to mark this kind of code explicitly so it can be filtered out in automated building/checking setups.

@mvdan
Copy link
Member

mvdan commented Mar 5, 2019

You can either have working examples as quasi-tests (https://golang.org/pkg/testing/#hdr-Examples) or put them under a hidden folder, like _examples. The latter will mean they won't be included in common runs like go test ./... or go build ./....

I don't see the need to add more complexity here. If that's not enough and you have something in mind, perhaps file a proposal.

@bcmills
Copy link
Contributor

bcmills commented Mar 5, 2019

Note that in module mode, you can wall off the examples by placing them in a separate module (by adding a go.mod file in the example portion of the directory tree).

@agnivade
Copy link
Contributor

agnivade commented Mar 7, 2019

I think this can be generalized to have the ability to ignore any code during building and testing. Using Example__ functions and build tags should be sufficient for this. You can also use the -run flag to control what you want to test.

Given the possible approaches in the above comments, I am going to close this one. If you have something specific in mind, please feel free to file a proposal. Thanks.

@agnivade agnivade closed this as completed Mar 7, 2019
@thepudds
Copy link
Contributor

thepudds commented Apr 8, 2019

Partially related to #31310.

@mvdan
Copy link
Member

mvdan commented Apr 8, 2019

I think there's one important distinction here with #31310; in my case, I do want the examples to be part of the main module, and I do want to build them with go test ./.... That issue is just about being able to selectively run them.

@thepudds
Copy link
Contributor

thepudds commented Apr 8, 2019

Hi @mvdan, very much agree they are distinct issues.

@nim-nim wrote above:

This kind of example code needs to be filtered in unit tests and dep downloads

and

go needs a way to mark this kind of code explicitly so it can be filtered out in automated building/checking setups.

Perhaps a solution for #31310 will at least partially help a some of the use cases described in the issue above if for example there is an ability to more easily selectively run those types of examples. Or perhaps not, including of course it depends on what the ultimate solution for #31310 might be.

@nim-nim
Copy link
Author

nim-nim commented Apr 9, 2019

I think there's one important distinction here with #31310; in my case, I do want the examples to be part of the main module, and I do want to build them with go test ./.... That issue is just about being able to selectively run them.

At that point I hope you understand your example code will effectively be part of your module API, and third-party modules are going to depend on it and call it in their own tests and code.

Treating (and marking) such code as part of the module sources is not a problem.

The problem is the vast number of examples which are not considered as module API by their authors, are not kept working (it’s “just and example”, users can complete/fix the code themselves), are not kept API-stable when they build at all, or demonstrate use in conjunction with lots of other third-party modules, inflating the module dependency footprint many times over.

So maybe there should be a way to mark differently those two classes of examples. I don't know. I only know than once we started checking seriously the third-party code we use, existing in-the-wild example code was a vast pit of build and test errors, to the point that trying to fix it was deemed hopeless. Now we just want to /dev/null it by default, since none of it is required for operation of other module code (as long as examples do not leak in the module API).

@golang golang locked and limited conversation to collaborators Apr 8, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

6 participants