Gnopher hole: Module VS Pkg VS Path VS Dir VS SubPkg VS SubModule VS SubDir VS SubPath ...

[moul]

Topic to discuss during an upcoming deep dive meeting.

To define:

• wording for people/documentation
• wording for implementation (consistancy)

Related discussions:

• feat: fix gno test for _test.gno and _filetest.gno files #945

To do:

• Update docs: bootstrap a glossary, with p/ and r/ #1043

[moul]

IMO:

• modules are the unit that defines a collection of packages as a whole that you can publish using addpkg (rename to addmod?).
• packages is what you import at the end, and you don't care if this is the top-level package of a module or a subpackage, and you also want to publish an import modules/packages that were published under a namespace just for code organization.

[waymobetta]

Agreed, I thought this addpkg was confusing since the functionality encapsulates more than just packages (ie, realms).

[tbruyelle]

Since package is commonly used in Go, I think what's the most confusing is the fact that /p is named a package. Because in the Go world, a simple realm is also a package.

Maybe the rename should be :

• /p -> /lib
• /r -> /rlm (just to match the same number of letters than lib)

Wtih this kind of rename, we can keep package/pkg to designate both lib and rlm, just like in Go.

[moul]

Uploading a p/ package with subpaths faces no restrictions since they're self-contained and separate from realms.

However, with r/ realms, we need to consider the dual perspective of an "independent importable package" within go/gno and the unique realm features like addressing, possible assets, and state management.

Decisions on incorporating Modules (Realms with subpaths) into GnoVM and enabling resource sharing remain pending. Note that gno.Machine won't understand Modules, but vmkeeper could adapt gno.Machine.

Without this feature, expecations may vary and inconsistencies could arise when uploading a realm with subpaths. A temporary solution is to validate and trigger panic("not yet supported") in such cases.

-> #1041

---

@tbruyelle Maybe the rename should be ...

p/ can stand for pure package.

So we only have packages, some of them are pure and some of them are realms.

Like in go where you can have library packages or main packages.

-> #1043

[jefft0]

After yesterday's discussion, I would expect that a p/ package is versioned but that an r/ realm is not. You can import an older version of a p/ package (using gno.mod), but you cannot import an older version of an r/ realm. (gno.mod does not allow r/ realms.) If that is true, then other consequences follow.

[moul]

Concerning versioning, components can exist in varied versions, each with distinct use and migration characteristics.

Ideally, continue using an earlier version of /p if it's working well. Encourage p/ developers to create smaller libraries for occasional updates or new optional features—like adding a fresh UI component to a UI library.
Special care is warranted for p/ packages housing structures intended for persistence (var myVar = myFooDep.Struct{}) or transfer to other contracts (myBarDep.Method(myFooDep.Struct{})). Widely-used packages will experience infrequent updates.

In the realm, only the latest version matters; previous versions might be deprecated or paused.
As other contracts might depend on earlier versions, we are considering effective design patterns to facilitate the evolution of r/, ensuring its accessibility from any version. This could entail dedicated storage realms or the implementation of migration features to patch a contract and update its dependency version.

For better user experience, it's logical for a r/ dependency to align with the latest version, especially during development.
Essentially, versioning is crucial during development, but in production, fewer updates are wiser. This aligns with Web3's stability practices, minimizing audits.

Personally, I'll forgo traditional versioning, opting for competing versions like p/moul/uifoo and p/moul/uibar, sidestepping compatibility concerns.

For more insights, check issue #694 on versioning.

[moul]

Closing, there is no ongoing action.

You are welcome to continue referring to this issue or reopening it if any uncertainties regarding those names arise again.

[thehowl]

Closing, there is no ongoing action.

I'd argue this is resolved when we have a definitions document with these defined?