-
Notifications
You must be signed in to change notification settings - Fork 17.9k
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
Comments
You can either have working examples as quasi-tests (https://golang.org/pkg/testing/#hdr-Examples) or put them under a hidden folder, like 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. |
Note that in module mode, you can wall off the examples by placing them in a separate module (by adding a |
I think this can be generalized to have the ability to ignore any code during building and testing. Using 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. |
Partially related to #31310. |
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 |
Hi @mvdan, very much agree they are distinct issues. @nim-nim wrote above:
and
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. |
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 |
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.
The text was updated successfully, but these errors were encountered: