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

doc/tutorial/create-module: describe use of multiple packages within the same module #47501

Open
bcmills opened this issue Aug 2, 2021 · 3 comments
Labels
Documentation modules NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@bcmills
Copy link
Contributor

bcmills commented Aug 2, 2021

The tutorial at https://golang.org/doc/tutorial/create-module starts by creating a package within one module, then (in https://golang.org/doc/tutorial/call-module-code) uses that package from within another module.

However, for most user projects we want to encourage users to develop all of their own packages within a single module — the dependency management is much simpler that way, and having multiple modules is only really an advantage if the user needs to release packages from within those modules on independent schedules.

It isn't entirely trivial to figure out how to use one package from another in the same module (see, for example, https://stackoverflow.com/q/68616619).

I think the “Create a Go module” tutorial should demonstrate the use of multiple packages within the same module before the (much more advanced) multi-module workflow.

CC @stevetraut @jayconrod @matloob

@bcmills bcmills added Documentation modules NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Aug 2, 2021
@bcmills bcmills added this to the Backlog milestone Aug 2, 2021
@stevetraut
Copy link

Thanks, Bryan.

The purpose of having two modules in the tutorial was to illustrate how to develop code that, after it's published, will be used as an external resource by other developers. The code in the two modules isn't intended to illustrate multi-module development -- one module is "in development" while the other is a mock client. So it's an opportunity to show workflow with for calling code in another module in order to test it before it's published (via replace).

I think that adding a topic about cross-package calls inside a module would be fine. But...

...having said that, I'll say that I think this tutorial was poorly conceived (by me). I think that a tutorial with its title should focus on module mechanics, including the interaction items you mention, but also versioning and some of the other common module development workflow items.

Instead, the tutorial starts off about modules, then skips through a lite Go language tour of error handling, slices, loops, unit testing, and ends with a few build/install commands.

I wonder if we should redesign this tutorial, possibly with the result of having two tutorials instead?

What do you think?

@bcmills
Copy link
Contributor Author

bcmills commented Aug 2, 2021

I think a redesign, perhaps with two or even three tutorials, sounds good. Perhaps one tutorial on writing a (multi-package) program within a module, and another on publishing (and testing) a library for others to use?

@stevetraut
Copy link

Yep. Those ideas work for me. I'll see what I can come up with and suggest something.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation modules NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

2 participants