@adonisjs/packages 0.1.1 → 0.1.3

package/README.md

@@ -17,6 +17,8 @@ pnpm sync <name> <repo>
 
 Example: `pnpm sync lucid adonisjs/lucid`
 
+For a package living in a monorepo, create `packages/<name>.yml` with a `directory` field pointing to the package folder (e.g. `directory: packages/core`) before running `pnpm sync <name> <repo>`.
+
 To sync with a branch different than the default, suffix the repo with `#repo-branch`, example: `pnpm sync lucid adonisjs/lucid#next`.
 
 ### Contribution
@@ -50,6 +52,8 @@ import db from '@adonisjs/packages'
 //      ^? { generatedAt, version, categories, packages }
 ```
 
+The npm package also includes `icons/`. Resolve an entry's `icon` filename relative to that directory and include it in your website's asset build.
+
 ### Schema
 
 | Field              | Auto sync | Description                                                                                                                  |
@@ -57,6 +61,7 @@ import db from '@adonisjs/packages'
 | `name`             | No        | Canonical name. Must match the filename. |
 | `description`      | Yes       | Short description, pulled from upstream `package.json`. |
 | `repo`             | No        | GitHub repository. Format is `org/name` or `org/name#branch`. |
+| `directory`        | No        | Folder of the package inside a monorepo, e.g. `packages/core`. `npm` and `description` are read from its `package.json`. |
 | `npm`              | Yes       | NPM package name. |
 | `icon`             | No        | Icon of the package from the [./icons](./icons) directory. |
 | `github`           | Yes       | GitHub URL, derived from `repo`. |
@@ -107,7 +112,19 @@ git push origin main
 git push origin "v$(node -p "require('./package.json').version")"
 ```
 
-Pushing the tag publishes the package. The tag must match the version in `package.json`. Published versions cannot be reused, including the version published manually during setup. The weekly healthcheck updates metadata but does not yet publish npm versions.
+Pushing the tag publishes the package. The tag must match the version in `package.json`. Published versions cannot be reused, including the version published manually during setup.
+
+### Weekly conditional releases
+
+After `Healthcheck (weekly)` succeeds on this repository's `main` branch, `release.yml` checks out the updated `main` and builds the registry. The healthcheck runs on Mondays at 06:00 UTC. A successful manual healthcheck also triggers this comparison.
+
+The prepare job downloads `@adonisjs/packages@latest` from npm and compares its `packages` and `categories` with the local build. Object key order, `generatedAt`, and the registry's `version` do not affect the comparison. Download errors and invalid JSON fail the job instead of triggering an initial publication.
+
+If the data matches, the job does nothing. Otherwise, it uses the next patch of the published version, or keeps the local manifest version if it is already higher. The GitHub App configured for the healthcheck commits only `package.json`, creates `vVERSION`, and pushes the commit and tag atomically. If `main` advanced, the push fails rather than releasing an outdated checkout. The tag starts the existing OIDC publish job in `release.yml`; the prepare job never publishes to npm. Prepare and publish runs share a concurrency group without cancelling an active run.
+
+If publishing fails after the tag was pushed, rerun that tag's failed `Release` run. The prepare job never replaces an existing tag. Changes to packaging or icon files alone require a manual release.
+
+To simulate the comparison, run `Release` from the Actions tab on `main` with `dry_run` enabled, which is the default. The simulation can update `package.json` in its temporary checkout but does not commit, push, tag, or publish. Disable `dry_run` only to prepare a real release.
 
 ## Healthiness bot