This document gathers some conventions for how we recommend naming your modules when authoring stuff in Warpforge. Also, on how to name releases (and how to label the items within them), when you get there.

<aside> 💡 Quick recap: in Warpforge Catalogs, content is published such that it can be referenced by a string tuple that looks like “catalog:{modulename}:{versionname}:{itemname}”.

An example reference is “catalog:warpsys.org/bash:v5.1.16-3:linux-amd64-zapp”.

</aside>

tl;dr

• Module names: should look like a URL. “foobar.org/frob/noz", for example.
• Release names: are freetext strings! But typically look like some kind of version info — e.g., typically, they start with a “v”, and typically there’s some dotted numbers after that — e.g. “v1.2.3”.
• Item labels: (the third part of a catalog lookup tuple) are freetext strings too — usually these are used to describe some architecture information. Example strings are “src” and “linux-amd64”.

Module Names

• tl;dr: Module names should look like a URL. “foobar.org/frob/noz", for example.
  • “mycompany.org/ourteamname/theproject" is a typical convention.
• Pick a namespace you “own” as a prefix. (URLs are a great choice for this because that topic is already addressed elsewhere.)
  • That includes if you're repackaging someone else's code — don't namesquat on their domain, because maybe they'll join us and do their own upstream packaging in the future (So: for example, we packaged GCC; but we did it under warpsys.org/gnu/gcc rather than under gnu.org/*.)
• How is name ownership enforced?
  • It isn’t! In your local workspace, on your own computer, you can do anything you want, and nobody can stop you.
  • But if you expect your releases to get syndicated around by other package set curators, so people can find it… you might find that they enforce some rules 😉
• Because module names end up being shown to users pretty frequently, and because they also sometimes get mapped onto filesystems, not all names are legal. We’ve reserved some characters.
  • Underscores at the start of module name path segments are reserved! So, “foo.org/_bar” is not a legal Warpforge module name.
  • Generally it’s recommended to keep things in the [-a-zA-Z0-9]+ range.

Release Names

• Release names are freetext strings!
  • “v1.2.3” is a valid release name.
  • “2022-12" is also a valid release name.
  • “raring-ringtail” is also a valid release name.
• Typically, people use release names look like some kind of version info with some numbers. If you’re into that, we recommend some further conventions:
  • Typically, we recommend version names start with a “v”. (People just like the visual consistency of that.)
  • Typically there’s some dotted numbers after that — e.g. “v1.2.3”. This can feel roughly like SemVer. Or it can feel like CalVer. (We’re not being prescriptive about this.)
  • If you end up “re-releasing” something — meaning, changing the build and package instructions in the plot, while still building from the same source code — we recommend suffixing a dash and then another incrementing version number to the end.
    • e.g. the second time we built a warpsys-flavor bash from the bash source “v5.1.16”, we released it as “warpsys.org/bash:v5.1.16-2”.
  • None of these are meant to be weird or surprising conventions :) We’re just trying to describe what people seem to do, already, for quick reference.
• Remember, though: release names do not have to be numbers. It is a convention at most. One can also use phrases like “raring-ringtail” as a release name, and Warpforge tooling is totally fine with that.
  • So, do not assume that you can (nor should) try to sort release names as if they’re numeric!
    • Catalogs store releases in order. If you are working on tooling that needs a stable order for some reason (whether for display, or for version bumping, or whatever), use the serialized order in the Catalog!

Item Names