rockspec conventions

[goldenstein64]

Addons designed for LuaRocks will probably need to follow certain conventions so they can be easily identified and discovered.

This is what I propose:

• The package field (its name) should start with lls-addon-, to clearly differentiate them from normal rocks that offer functionality at runtime.

• If the addon reflects the types of an existing module, like penlight:

  • the package field should also reflect the original rock's package name, e.g. lls-addon-penlight.
  • the version field should start with the original rock's version followed by a dot and the addon rock's version, e.g. 1.14.0.1.0-1. Hopefully, this should make it so that if a rock decides to make the addon rock a build dependency, it only needs to specify something like "lls-addon-penlight ~> 1.14.0.1".

[goldenstein64]

Looking at part of the LuaRocks source here, versions are parsed into an array of integers using -, . and _ as separators. The revision is stored separately, starting from the end of the string. So 1.14.0-1.0-1 would be parsed as { 1, 14, 0, 1, 0, revision = 1 }.

My example, lls-addon-penlight ~> 1.14.0-1, wouldn't work properly because the last -1 in the target version would be parsed as the revision, i.e. { 1, 14, 0, revision = 1 }. It would be better to avoid this using a different separator like 1.14.0_1.

You could probably hack out the revision parsing by putting a separator after the last number, like 1.14.0-1., but it seems too easy to overlook the importance of that dot.

[carsakiller]

Good thinking!

I am a bit torn on the package name specifics. luacats is short and sweet, but LuaCATS is specifically about the comment and type system, and not really about addons that can have plugins and potentially more in the future. llsaddon-x is terrible and lls-x doesn't seem unique enough. A quick search of luacats brings up nothing whereas lls brings up two at least mostly unrelated rocks. I have personally only quickly played around with the plugin feature, and still, to me, addons are 99% about definitions, which I believe is reflected in their usage.

Either way, I have registered manifests for both luacats and lls-addons. Although, I am not sure how necessary these are given the proposed naming prefix. I suppose it could make organizing and indexing easier/faster. Would recommending that everyone upload their rock to one of these be a good idea or a hassle, as now everyone has to do --server=https://luarocks.org/m/luacats?

The versioning for ccTweaked might get interesting as it is versioned [mc-major.mc-minor.mc-patch] ccT-major.ccT-minor.ccT-patch. I guess I would do <ccT-major>.<ccT-minor>.<ccT-patch>_<types-revision>, so 1.116.1_2, for example?

[goldenstein64]

I am a bit torn on the package name specifics. luacats is short and sweet, but LuaCATS is specifically about the comment and type system, and not really about addons that can have plugins and potentially more in the future. llsaddon-x is terrible and lls-x doesn't seem unique enough. A quick search of luacats brings up nothing whereas lls brings up two at least mostly unrelated rocks. I have personally only quickly played around with the plugin feature, and still, to me, addons are 99% about definitions, which I believe is reflected in their usage.

You're right about luacats-x being the wrong prefix for LLS addons, since addons have more restrictions and features on top of LuaCATS and can evolve separately. Plus, it's not exactly short and sweet, 8 extra characters is still a decent amount in my opinion. Honestly, I just wanted to be consistent with the manifest name.

LuaRocks uses a rather verbose naming scheme for rocks related to itself like luarocks-build-x. Maybe we could follow precedent and use something like lls-addon-x as a prefix.

Either way, I have registered manifests for both luacats and lls-addons. Although, I am not sure how necessary these are given the proposed naming prefix. I suppose it could make organizing and indexing easier/faster. Would recommending that everyone upload their rock to one of these be a good idea or a hassle, as now everyone has to do --server=https://luarocks.org/m/luacats?

I think the prefix is all that is needed to browse and search addons. I think it makes the process a lot simpler for both users and developers. The best thing about a non-root manifest is it provides a semantic grouping of rocks for the LuaRocks CLI, and it's easy to provide a link

The versioning for ccTweaked might get interesting as it is versioned [mc-major.mc-minor.mc-patch] ccT-major.ccT-minor.ccT-patch. I guess I would do <ccT-major>.<ccT-minor>.<ccT-patch>_<types-revision>, so 1.116.1_2, for example?

I'm leaning towards yes. It may be safer to add another revision version in case the rockspec changes, i.e. 1.116.1_2-1.

[goldenstein64]

The versioning for ccTweaked might get interesting as it is versioned [mc-major.mc-minor.mc-patch] ccT-major.ccT-minor.ccT-patch. I guess I would do <ccT-major>.<ccT-minor>.<ccT-patch>_<types-revision>, so 1.116.1_2, for example?

The version restriction doesn't really apply in your case though, since it's emulating an environment, not reflecting a module.

[goldenstein64]

I just tried writing a rockspec for LuaFileSystem, and I got a concerning lint error while running luarocks make:

Error: .\rockspec\lls-addon-luafilesystem-1.8.0_1.0.0-1.rockspec: 
  Type mismatch on field version: 
  invalid value '1.8.0_1.0.0-1' does not match '[%w.]+-[%d]+' (using rockspec format 3.0)

So the underscore separator does not work here, likely because of the rockspec_format field, which I would want to keep on at least 3.0.

I think I'm going to look into how other type definition packages do versioning.

• TypeScript types: https://www.semver-ts.org/
  • They follow the reflected module's major and minor version, but patches are kept independent, e.g. 1.8.0 (where the 0 is the addon module's patch version).
• Python typeshed: https://github.com/python/typeshed#package-versioning-for-third-party-stubs
  • They follow the reflected module's semantic version followed by the date the module was updated, e.g. 1.8.0.20230205.
• Ruby-Sorbet types: https://github.com/Shopify/rbi-central
  • They keep their types contained in this repository. While there are tools to target a certain version of a module, there is no mechanism for versioning the types themselves.
• JS-Flow types: https://github.com/flow-typed/flow-typed
  • Like the above, types are contained in this repository, and there are tools to target a certain version of a module, but not for versioning the types themselves.
• Lua-Teal types: https://github.com/teal-language/teal-types
  • Like the above, types are contained in this repository. There are no versioning mechanisms here.

[goldenstein64]

Just to settle on a format for now, I'm going to opt for starting with the reflected module's version followed by a dot separator and at least one additional version number. In my case, it would be 1.8.0.1.0.0, but it could be shortened to 1.8.0.1 since the codebase is low complexity.