Module Naming Conventions

Amber Modules Naming Conventions

Def. 1: An Amber Module is a collection of one or more Amber packages (each in its .st and .js file), located in one repository.

Conclusion 1: If an Amber Module is published in bower, the whole content is accessible via single bower name.

Note 1: Conclusion 1 is unidirectional. There can be a repo that hosts more modules.

In the majority of cases, an Amber Module contains one namespace, though it can contain more if desired. Amber core itself is such an Amber Module (it contains the amber and amber_core namespaces). Having more namespaces should be rare in bite-sized modules, it may be not so rare for large frameworks, though they are also encouraged to split to more distinct pieces.

This document gives recommendations on how to choose module bower names, namespaces and packages. It will only cover one-namespace modules.

Categories

There are three categories of Amber modules:

1. Amber core itself - this is the amber repository itself.
2. Amber-contrib modules - these are library modules that are maintained by the Amber team as part of the basic Amber system. If the Amber team maintains an app (Helios is an example), it should be treated as a userland module.
3. Userland modules - the rest, not part of the contrib nor the core, governed by their respective contributors,

Amber core naming

• bower name: amber
• repo: amber-smalltalk/amber
• namespace(s): amber is the namespace reserved for Amber core, as well as any namespace beginning with amber_, at the moment amber_core and amber_cli are used
• package(s): Mostly two-word, dash separated, from Kernel-Xxx, Compiler-Xxx or Platform-Xxx group, though non-dashed ones are also present. Kernel-Xxx should all be in Amber core, others may be partly moved to contrib modules.

Amber contrib modules naming

The status quo is chaotic for contrib modules. None of them are in bower outside the incubator space in Amber repo itself, in the contrib directory. Namespaces are too long atm, like amber-contrib-web. Some other candidates for contrib, like domite have one-word namespace.

This is a proposal for a consistent naming of contrib modules.

• bower name: if not part of amber, use amber-contrib-foo
• repo: if not part of amber-smalltalk/amber, use amber-smalltalk/amber-contrib-foo
• namespace(s): amber/foo
• package(s): See below in userland modules.

Note: amber-compat-xxx modules are also forming a distinct group, similar to contrib modules. But these are often not the typical package containers, they are more infrastructure hacks. For these, the the status quo should be preserved: amber-compat-bar as bower name, repo name and namespace, should they need one, at the same time.

Userland modules naming

Status quo is less chaotic mostly people either adopt amber init-proposed amber-foo, or just use the shortname. This is what is proposed here, as well.

• bower name: Use amber-foo or foo. If "foo" is too generic, lean towards the former
• repo: owner/amber-foo or owner/foo, depending on previous line
• namespace(s): amber-foo or foo, copying the first line
• package(s): Use standard Smalltalk conventions using common prefix: Foo, Foo-DistinctPart etc. with Foo-Tests or FooTests. If you wrap a known JS library, it is recommended that prefix be Wrappers-JSLib (as is used in Wrappers-JQuery atm).