what practice should we follow for example modules sources?

[kral2]

Problem definition

When providing HCL code in examples directory to illustrate a module’s features, we have to define the source for the module. Simplifying a bit, there are two main choices: the git repo or the public registry.

Regardless of the choice for OCI Terraform modules, it should be consistent across examples and modules.

proposed Solution

Only module developers should have to git clone the module repo, while users should consume from the public registry.

As a consequence, examples should use the registry as source, so the users can start consuming the module directly, without having to manually git-clone the module first.

This pattern helps driving download stats on the public register and get better exposure.

I can understand that having local path is convenient when testing the modules. But the examples directory’s primary usage is for a user to consume the module with minimum interaction.

We can definitely create another test folder with hcl code referring to local path for testing purpose, used during development.

I would advise to revert the change in PR #84 back to source from public registry.

Originally posted by @kral2 in #84 (comment)

[snafuz]

@kral2 - I see your point. The problem we were trying to solve here is to avoid that the examples are not working when someone just clone the repo.
I’ll think about how we can address both needs

[kral2]

Side note: @snafuz, could you convert this gh issue into a gh discussion?

Why would examples sourced from the public registry not work when cloning the repo? Suppose some recently merged commits are not part of a release tag yet. In that case, this is expected and temporary behavior related to a recent update. But examples code probably lives more time as part of a release tag than not.

This discussion also triggers the choice of specifying a module version or not. I would prefer not to set the module version to default using the latest available version. If a user needs to use a specific version of the module (not the latest) or one that is not even released yet, that's an advanced use case and could justify some extra steps, like changing the source or specifying a particular version.