docs(SPEC): add specification of modules #5224

nathanielc · 2022-09-23T18:55:07Z

The implementation of this work is still in-progress see #4296

Checklist

Dear Author 👋, the following checks should be completed (or explicitly dismissed) before merging.

✏️ Write a PR description, regardless of triviality, to include the value of this PR
🔗 Reference related issues
🏃 Test cases are included to exercise the new code
🧪 If new packages are being introduced to stdlib, link to Working Group discussion notes and ensure it lands under experimental/
📖 If language features are changing, ensure docs/Spec.md has been updated

Dear Reviewer(s) 👋, you are responsible (among others) for ensuring the completeness and quality of the above before approval.

Marwes · 2022-09-26T17:46:34Z

docs/SPEC.md

+
+Examples
+
+    import "foo/module"             // imports the latest version 0.x or 1.x version of the module


This will be ambiguous with standard library modules as it is currently (did you mean the user module "array" or the standard library "array"?). For the existing standard library we can just reserve the names for all existing packages, but that won't work if we want to add a new packages so maybe we also want to add and reserve a std prefix for the standard library?

I've seen things in the JS space where importers use like ~/... to say, "relative to the project's node_modules dir."

It could be useful to have something as a prefix to indicate the importer to use (registry vs stdlib).

docs/SPEC.md

nathanielc · 2022-11-02T23:08:59Z

docs/SPEC.md

+| GET    | $base/$module/@v/$version.zip | Returns a zip file of the contents of the module at a specific version.                                                                                    |
+| GET    | $base/$module/@latest         | Returns the highest released version, or if no released versions exist the highest pre-release version of the given module in plain text on a single line. |
+| GET    | $base/$module/@pre            | Returns the highest pre-released version of the given module in plain text on a single line.                                                               |
+| POST   | $base/$module/@v/$version     | Publish a new version of the module where the POST body contains multipart formdata for the contents of the module.                                        |


The @v delimiter is no longer necessary since a module path is at most two path elements, of the form name/v# where # is a number >= 2. We needed a rule to distinguish module paths from package paths and it so happens we can reuse that rule for the registry API.

Should we remove it?

We discussed and we are going to leave @v in place. We have already implemented it and it helps future proof the API so it makes sense to leave it be.

How does POST and @pre work---is there a way to specify that the version you are publishing is release or pre-release?

nathanielc · 2022-11-02T23:11:41Z

NOTE: This specifies two changes to the current implementation of the registry API.

the v is required anywhere a version is used
the POST no longer expects a .zip extension.

wolffcm

This looks reasonable to me, but I had some questions about what it means to use @pre.

wolffcm · 2022-11-07T23:38:18Z

docs/SPEC.md

+Example:
+
+    @registry("modules", "http://localhost/modules")
+    @registry("example.com", "https://example.com/api/modules")


The registry attribute needs to appear before the package clause, right? If so, it would be worth mentioning here.

wolffcm · 2022-11-07T23:45:58Z

docs/SPEC.md

+An import path follows this grammar:
+
+    ImportPath       = ModulePath [ "/" PackagePath ] [ Version ] .
+    ModulePath       = PathElement [ "/" PathElement ] [ MajorVersion ] .


It might make it clearer to write it like this

Suggested change

ModulePath = PathElement [ "/" PathElement ] [ MajorVersion ] .

ModulePath = RegisteryName [ "/" ModuleName ] [ MajorVersion ] .

RegistryName = PathElement

ModuleName = PathElement

wolffcm · 2022-11-07T23:51:44Z

docs/SPEC.md

+
+When no version information is provided the latest version of the module is used.
+A _minimum_ version may be specified.
+An import may also specify the version `pre` which is the most recent pre-release version of the module.


So pre exists to let users get the very latest version, sort of like Rust nightly?

Everything that gets published bumps the version number, right? So I don't see how this would be useful.

I am expecting that @pre refers to an explicit pre-release using semantic versioning for pre-release versions. I am expecting that clients (i.e. the UI) will leverage pre-releases to pre-publish or preview a module before doing a real publish of the module. This way users can test their modules without risk of breaking existing consumers.

I imagine a workflow like this:

Publish a module foo

Consume module foo in various other scripts

Decide to improve foo

Publish a pre-release of foo.

Use @pre is specific scripts to ensure its working

Publish a normal release of foo, all other scripts are now upgraded

This work across major versions as well as @pre applies to within a single major version. Meaning there can be a different pre-release for each major version.

wolffcm · 2022-11-08T00:01:30Z

docs/SPEC.md

+| GET    | $base/$module/@v/$version.zip | Returns a zip file of the contents of the module at a specific version.                                                                                    |
+| GET    | $base/$module/@latest         | Returns the highest released version, or if no released versions exist the highest pre-release version of the given module in plain text on a single line. |
+| GET    | $base/$module/@pre            | Returns the highest pre-released version of the given module in plain text on a single line.                                                               |
+| POST   | $base/$module/@v/$version     | Publish a new version of the module where the POST body contains multipart formdata for the contents of the module.                                        |


How does POST and @pre work---is there a way to specify that the version you are publishing is release or pre-release?

nathanielc · 2022-11-08T18:56:26Z

How does POST and @pre work---is there a way to specify that the version you are publishing is release or pre-release?

The pre-release is part of the semantic version spec. Therefore it becomes straightforward to create a pre-release when publishing by specifying a version string that is a pre-release.

wolffcm

Looks great.

wolffcm · 2022-11-08T20:35:42Z

docs/SPEC.md

@@ -1460,7 +1460,7 @@ Module paths need not be unique across different registries.

 #### Registry attribute

-The `registry` attribute defines the available registries.
+The `registry` attribute defines the available registries and must preceed a package clause.


Just a nit, typo in the word "precede".

The implementation of this work is still in-progress see #4296

nathanielc changed the base branch from docs/editions to master September 23, 2022 18:55

Marwes reviewed Sep 26, 2022

View reviewed changes

onelson reviewed Sep 27, 2022

View reviewed changes

docs/SPEC.md Show resolved Hide resolved

nathanielc mentioned this pull request Oct 25, 2022

Download Flux modules within runtime as part of Salsa query #5310

Closed

nathanielc force-pushed the docs/modules branch from acca97a to 840245b Compare November 2, 2022 23:01

nathanielc commented Nov 2, 2022

View reviewed changes

nathanielc marked this pull request as ready for review November 2, 2022 23:09

nathanielc requested a review from a team as a code owner November 2, 2022 23:09

nathanielc requested review from wolffcm and removed request for a team November 2, 2022 23:09

nathanielc force-pushed the docs/modules branch from 840245b to 392a48a Compare November 2, 2022 23:19

wolffcm reviewed Nov 8, 2022

View reviewed changes

nathanielc requested a review from wolffcm November 8, 2022 18:59

wolffcm approved these changes Nov 8, 2022

View reviewed changes

docs(SPEC): add specification of modules

63d4eca

The implementation of this work is still in-progress see #4296

nathanielc force-pushed the docs/modules branch from 02d46f7 to 63d4eca Compare November 8, 2022 20:37

nathanielc merged commit 1cdebda into master Nov 8, 2022

nathanielc deleted the docs/modules branch November 8, 2022 22:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(SPEC): add specification of modules #5224

docs(SPEC): add specification of modules #5224

nathanielc commented Sep 23, 2022

Marwes Sep 26, 2022

onelson Sep 27, 2022

nathanielc Nov 2, 2022

nathanielc Nov 4, 2022

wolffcm Nov 8, 2022

nathanielc commented Nov 2, 2022

wolffcm left a comment

wolffcm Nov 7, 2022

wolffcm Nov 7, 2022

wolffcm Nov 7, 2022

nathanielc Nov 8, 2022

wolffcm Nov 8, 2022

nathanielc commented Nov 8, 2022

wolffcm left a comment

wolffcm Nov 8, 2022


		Examples

		import "foo/module" // imports the latest version 0.x or 1.x version of the module

-    ModulePath       = PathElement [ "/" PathElement ] [ MajorVersion ] .
+    ModulePath       = RegisteryName [ "/" ModuleName ] [ MajorVersion ] .
+    RegistryName     = PathElement
+    ModuleName       = PathElement

docs(SPEC): add specification of modules #5224

docs(SPEC): add specification of modules #5224

Conversation

nathanielc commented Sep 23, 2022

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathanielc commented Nov 2, 2022

wolffcm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathanielc commented Nov 8, 2022

wolffcm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment