@synopackageland/cli 0.30.0 → 0.32.0

package/skills/reference/upstream-fork.md

@@ -11,6 +11,30 @@ under `synology/`, such as DSM install wizards and gateway pages; leave upstream
 UI/locale strings and release notes unchanged, and exclude upstream source from
 any future punctuation checker.
 
+## Maintainer and distributor
+
+If you package someone else's open-source project, set `maintainer` to the original
+project/owner (prefer the project's own team/org name, else the owner's display
+name, else login), `metadata.maintainer_url` to the upstream repository, and
+**yourself** as `metadata.distributor` / `metadata.distributor_url`. Only your own
+Apps use your publisher as maintainer. Syno Package Land is the distributor only
+when it distributes the App; this rule applies to every third-party developer.
+
+Pass `--upstream <repo-url>` (or retain the `upstream` Git remote), your verified
+`--upstream-maintainer <project-team>` when known, and `--publisher <name>` /
+`--publisher-url <url>` to `init --upstream-fork`. Publisher defaults come from
+`SYNOPKGLAND_PUBLISHER` / `SYNOPKGLAND_PUBLISHER_URL`. The CLI tries the public
+GitHub owner profile with a bounded lookup, using its display name then login.
+Offline or unsupported hosts leave an explicit maintainer TODO. Missing publisher
+configuration leaves a distributor TODO. Resolve these manually before release.
+`metadata.upstream` records the repository; `check` warns, without failing, for
+missing attribution or a maintainer that equals the distributor. The fork layout
+also enables this warning without `metadata.upstream`.
+
+These metadata fields become standard SPK INFO fields; upstream source stays
+unchanged. Catalog attribution may change before rebuilding; installed INFO
+changes only after an SPK upgrade.
+
 ## Decide whether to expose AI control
 
 Ask whether the user needs AI control unless they have already explicitly requested it.
@@ -37,11 +61,12 @@ git clone <your-fork-url> app
 cd app
 git remote add upstream <upstream-url>
 synopkgland init -t compose --upstream-fork --package MyApp \
-  --upstream-image owner/app --health-path /actual-readiness --health-status 200 .
+  --upstream https://github.com/owner/app --publisher "Your team" \
+  --publisher-url https://example.com --upstream-image owner/app --health-path /actual-readiness --health-status 200 .
 ```
 
 Replace `owner/app` with the verified official repository. `init` does not guess
-its publisher or make network requests. Configure `synology/upstream-recipe.json`:
+the official image publisher. Only attribution uses a best-effort GitHub profile lookup. Configure `synology/upstream-recipe.json`:
 `repository`, the actual Compose `service`, and `imageTag: tag` (exact upstream
 tag) or `version` (strip the leading `v` only if the official image uses that
 spelling). Adjust the App's port, storage and DSM login adapter before committing.
@@ -78,7 +103,9 @@ workaround with the framework ownership mechanism once available and verified.
 ## Native: official release binaries or a source build hook
 
 ```sh
-synopkgland init -t native-go --ui plain --upstream-fork --package MyApp .
+synopkgland init -t native-go --ui plain --upstream-fork --package MyApp \
+  --upstream https://github.com/owner/app --publisher "Your team" \
+  --publisher-url https://example.com .
 ```
 
 Native Apps can stage official release binaries pinned by **SHA-256**, or compile
@@ -180,3 +207,11 @@ returns 503 even when the gateway is down. Availability is not identity attestat
 Declare only Container Manager-capable `arches`/INFO platforms; exclude unsupported
 NAS architectures and review models in each family. Actual missing-package wizard
 behavior and DSM's dependency not-ready behavior remain device acceptance items.
+
+## Release checklist
+
+- Verify the original project/team or owner is the maintainer, its repository is
+  `metadata.maintainer_url` / `metadata.upstream`, and your publisher is the distributor
+- Resolve attribution TODOs and review all `check --json` warnings
+- Inspect the built SPK INFO attribution, preserve notices/source correspondence,
+  and verify the selected upstream release before publishing