docs(lux.toml): source templates (#10)

Author: mrcjkb

docs/guides/lux-toml.md

@@ -29,7 +29,7 @@ for example when [publishing a rock](/guides/publishing).
 
 ### `version`
 
-The rock's version (mandatory).
+The rock's version (optional).
 
 ```toml title="example"
 version = "1.0.0"
@@ -49,6 +49,11 @@ However, more complex versions that are not SemVer compliant
 (for example ,`1.0-rc1` instead of `1.0.0-rc1`) will be treated as Dev versions, 
 which cannot be compared with SemVer versions.
 
+If the version is not set in the `lux.toml` and the project is in a git repository,
+Lux will search the `HEAD` for a SemVer compliant git tag (with an optional `v` prefix).
+If one is found, it will be used to parse the package version.
+Otherwise, the version is assumed to be `dev`.
+
 ### `description`
 
 Metadata that will be published to luarocks.org (optional).
@@ -67,6 +72,38 @@ maintainer = "neorocks org"
 labels = [ "neovim", "tls", "https" ]
 ```
 
+## Source
+
+To install a remote package, Lux needs to know where to find the source.
+This may vary, depending on the package's version.
+Unlike a Lua rockspec, Lux provides a mechanism for generating a [published](/guides/publishing)
+rockspec's source.
+
+You can declare templates for both SemVer and dev releases:
+
+```toml title="example"
+[source]
+url = "https://host.com/owner/$(PACKAGE)/archive/refs/tags/$(REF).zip"
+dev = "git+https://host.com/owner/$(PACKAGE).git"
+```
+
+Or:
+
+```toml title="example"
+[source]
+url = "https://host.com/owner/$(PACKAGE)/archive/refs/tags/v$(VERSION).zip"
+dev = "git+https://host.com/owner/$(PACKAGE).git"
+```
+
+When publishing a rock, Lux will perform the following variable substitutions:
+
+- `$(PACKAGE)`: The package name.
+- `$(VERSION)`: The package version 
+                (generated from a git tag if not declared in the `lux.toml`).
+- `$(REF)`: The git tag or revision
+            (priority: 1. SemVer tags; 2. tags; 3. revision (commit SHA)).
+- You may also specify environment variables with `$(<VAR_NAME>)`.
+
 ## Dependencies
 
 Lux differentiates between five types of dependencies:

docs/guides/project-updating.md

@@ -27,29 +27,6 @@ If you are creating your releases manually, consult your Git forge and see if th
 is a "Releases" section from where you can create a new release. If not, create a git tag
 named after your release, for example: `2.0.0`.
 
-## Reconfiguring the Source URL
-
-Because the entire repository (including the `lux.toml`) is put under version control,
-you can safely prepare the `lux.toml` for the release of a new version.
-
-To prepare a new release, open your project's `lux.toml` and edit the following section:
-```diff title="lux.toml"
-package = "my-lua-project"
-version = "0.1.0"
-
-[source]
-url = "git+https://github.com/my-username/my-project"
-- tag = "v0.1.0"
-+ tag = "v0.2.0"
-
-...
-```
-
-:::important
-Note the value provided to `tag` - tools like `release-please` automatically prefix the versions
-with a `v`. If you made a release manually, then make sure the name is identical to whatever you set.
-:::
-
 ## Publishing
 
 We're now ready to publish all of our changes to [luarocks.org](https://luarocks.org).

docs/guides/publishing.md

@@ -25,6 +25,8 @@ First, you must choose a version number. Lux requires that all projects follow
 the [Semantic Versioning](https://semver.org/) specification. If your project is still unstable,
 mark it as version `0.1.0`. If your code is ready for general use, mark it as
 version `1.0.0`.
+Lux can infer the version from a SemVer compliant git tag (with an optional `v` prefix).
+In this case, you do not need to declare the version in your `lux.toml`.
 
 There are many ways to keep track of versioning or releases. We recommend a
 tool like [release-please](https://github.com/googleapis/release-please), which automatically
@@ -38,27 +40,33 @@ creating a git tag named after a version will also suffice.
 ## Configuring a Source URL
 
 With the URL in hand, open your project's `lux.toml` and add the following section:
+
 ```toml title="lux.toml"
 package = "my-lua-project"
 version = "0.1.0"
 
 # highlight-start
 [source]
-url = "git+https://github.com/my-username/my-project"
-tag = "v0.1.0"
+url = "https://github.com/my-username/my-project/archive/refs/tags/$(REF).zip"
+dev = "git+https://github.com/my-username/my-project.git"
 
 # highlight-end
 
 ...
 ```
 
-:::important
-We must provide the `git+https://` protocol to instruct Lux to use `git`.
+`url` is a template for a SemVer release URL; in this case, a ZIP archive for the release tag.
+Note the `$(REF)` variable in the URL template. Lux will substitute it with the tag or revision.
+`dev` is a template for a dev release URL, which is a git URL in this example.
+
+:::note
+You could also specify `v$(VERSION)` to inject the version instead.
+Additionally, you can inject the package name via `$(PACKAGE)`
+or any environment variable via `$(VAR_NAME)`.
 :::
 
 :::important
-Also, note the value we provided to `tag` - tools like `release-please` automatically prefix the versions
-with a `v`. If you made a release manually, then make sure the name is identical to whatever you set.
+We must provide the `git+https://` protocol in the `dev` URL template to instruct Lux to use `git`.
 :::
 
 ## Acquiring an API Key