docs: update with make_archive_script changes

apkg/compat.py

@@ -14,12 +14,16 @@ COMPAT_LEVEL = 5
 
 
 COMPAT_LEVEL_NOTES = {
-    5: ('0.x.0', """Forward incompatible update.
+    5: ('0.6.0', """Forward incompatible update, changes required:
 
-## New make-archive interface
+## new make_archive_script YAML interface
 
-stdout output of make-archive scripts is now parsed by apkg in full,
-any unrelated messages should go to stderr"""),
+make_archive_script stdout is now expected to be in YAML format, any messages
+should go to stderr.
+
+Edit your make_archive_script to output like this:
+
+archive: pkg/archives/dev/banana-1.2.3.tar.gz"""),
     4: ('0.5.0', """Forward compatible update, no action required."""),
     3: ('0.4.0', """Forward compatible update, no action required."""),
     2: ('0.3.0', """Forward compatible update for most users.

docs/commands.md

@@ -49,25 +49,13 @@ current distro: arch / Arch Linux
 [project.make_archive_script](config.md#projectmake_archive_script)
 config option to be set.
 
-This command will only succeed when the script finishes successfully (with
-exit code 0) and it outputs the resulting archive (and potentially other
-information) to stdout.
-
-The interface differs based on compat level:
-
-- level <= 4:
-  Last line of the script's stdout is taken to be the generated archive, all
-  other lines are ignored. Upstream version is extracted from archive name.
-- level >= 5 behaviour is different (richer):
-  - lines with `#` as the first character are currently ignored (but it is
-    encouraged that stderr is used for any reporting)
-  - other lines are expected to be in the form of `<tag>[:<argument>] <value>`
-    where:
-    | Tag name | Occurrence | Supports argument? | Description |
-    | --- | --- | --- | --- |
-    | archive | exactly once | no | upstream sources |
-    | version | at most once | no | signals upstream version, if not present, version is extracted from archive |
-    | component | optional, multiple | yes | additional sources, argument signals the "component" name for `deb` scheme |
+This command will only succeed when `make_archive_script` script finishes
+successfully (with exit code 0) and it outputs the resulting archive (and
+potentially other information) to stdout.
+
+See
+[project.make_archive_script](config.md#projectmake_archive_script)
+for expected script output.
 
 Resulting files are copied to `pkg/archives/dev/` or to `--result-dir`.
 

docs/config.md

@@ -28,41 +28,66 @@ This is available to templates through {% raw %}`{{ project.name }}`{% endraw %}
 
 ### project.make_archive_script
 
-In order to create packages from your project source, `apkg` requires a script
-which creates archive from current project state.
+In order to create packages from your project source,
+[apkg make-archive](commands.md#make-archive) requires a script which creates
+archive from current project state.
 
-The script MUST return the path to created archive on the first line of its
-`stdout`.
+Include such script in your project and specify it using `project.make_archive_script`:
 
-The created archive MUST contain version string, for example:
+```toml
+[project]
+make_archive_script = "scripts/make-archive.sh"
+```
+
+When the script finishes successfully, it MUST exit with return code 0 and
+print valid YAML to its stdout.
+
+The script MUST output `archive` path:
 
 ```
-banana-v1.2.3.tar.gz
+archive: pkg/archives/dev/banana-v1.2.3.tar.gz
 ```
 
-The script MAY output additional files (such as signatures) and print their
-paths on individual `stdout` lines after the main archive.
+The script MAY output `version`:
 
-!!! Tip
-    The script SHOULD create archives with **unique version strings** for individual
-    VCS commits if using VCS. This isn't strictly required by `apkg`, but it will
-    save you a lot of conflicts and needless work later on.
+```
+version: '1.2.3'
+```
 
-Include such script in your project and then point to it using `make_archive_script`:
+When omitted, `version` is guessed from `archive` file name.
 
-```toml
-[project]
-make_archive_script = "scripts/make-archive.sh"
+The script MAY output additional files as `components`:
+
+```
+components:
+  extra: pkg/archives/dev/extra-v0.5.tar.gz
+  files: pkg/archives/dev/files.tar.gz
 ```
 
+The script SHOULD create archives with **unique version strings** for individual
+VCS commits if using VCS. This isn't strictly required by `apkg`, but it will
+save you a lot of conflicts and needless work later on.
+
+It's strongly recommended to **reuse** the same script in the upstream archive
+creation during official release so that this **code gets properly tested** on
+regular basis - it's used on most `apkg` operations.
+
+`apkg make-archive` copies the resulting `archive` (and `components` if any) to
+`pkg/archives/dev` output directory. You can save some disk space and I/O by
+creating the `archive` (and `components` if any) directly in `pkg/archives/dev` in your `make_archive_script`.
+
 Most projects which use `apkg` have the script in `scripts/` directory for
 historic reasons, but feel free to put it into `distro/scripts/` or anywhere
 else you want.
 
-!!! Tip
-    It's strongly recommended to **reuse** the same script in the upstream archive
-    creation during official release so that this **code gets properly tested** on
-    regular basis - it's used on most `apkg` operations.
+{{ added_in_version('0.6.0', compat=5, action="Changed") }}
+
+For compat level 4 and older, `make_archive_script` is expected to return
+archive file name as last line of its stdout:
+
+```
+pkg/archives/dev/banana-v1.2.3.tar.gz
+```
 
 `make_archive_script` **examples** in the wild:
 

docs/news.md

 # apkg news
 
+## apkg 0.6.0
+
+**Unreleased** - in development
+
+### Compat Level 5 News
+
+- flexible YAML output for
+  [make_archive_script](config.md#projectmake_archive_script),
+  [make-archive](commands.md#make-archive), and
+  [get-archive](commands.md#get-archive)
+    - [make_archive_script](config.md#projectmake_archive_script) can specify
+    explicit `version`
+    - [make_archive_script](config.md#projectmake_archive_script) can produce
+      additional files (`components`)
+
 ## apkg 0.5.1
 
 Released 2024-06-24