# Releasing

Maintainer notes for
`@wizardry.steamworks/node-red-contrib-roomba980-local`. The project is
distributed through three channels:

* **SVN** — canonical source: <https://svn.grimore.org/node-red-contrib-roomba980-local>
* **Verdaccio** — self-hosted npm registry: <https://npm.grimore.org/>
* **npmjs.com / Node-RED Flow Library** — public distribution and listing

## 1. Prepare the version

1. Update the version in `package.json`.
2. Add an entry to `CHANGELOG.md`.
3. If the `dorita980` fork changed, refresh the vendored copy:

   ```sh
   DORITA980_SRC=/path/to/dorita980 npm run sync:vendor
   ```

   Then commit the fork separately and publish it to Verdaccio:

   ```sh
   cd /path/to/dorita980
   npm test
   npm publish --registry=https://npm.grimore.org/
   ```

4. Run the checks:

   ```sh
   npm install
   npm test
   npm pack --dry-run
   npm audit --omit=dev
   ```

   A default install must not contain the deprecated `request` chain.
   `request-promise` is an optional peer dependency used only for firmware
   1.x robots; firmware 2.x users do not install it.

5. Inspect the tarball. It must contain `package.json`, `README.md`,
   `LICENSE`, `NOTICE`, `CHANGELOG.md`, `dorita980/`, `vendor/` and
   `examples/`. It must not contain `test/`, `scripts/`, `RELEASING.md` or
   `node_modules/`.

6. Install the packed tarball into a scratch Node-RED user directory and
   confirm the nodes load without access to the private registry:

   ```sh
   npm pack
   mkdir -p /tmp/nr-release-test
   cd /tmp/nr-release-test
   npm init -y
   npm install /path/to/wizardry.steamworks-node-red-contrib-roomba980-local-<version>.tgz
   node -e "require('@wizardry.steamworks/node-red-contrib-roomba980-local/dorita980/dorita980.js')"
   ```

## 2. Commit to SVN

The repository is a standard SVN repository. Check out a `file://` working copy
for commits when the HTTPS endpoint is not usable non-interactively (for
example, when `gpg-agent` blocks the TLS client certificate):

```sh
svn checkout file:///mnt/grimore/svn/general/node-red-contrib-roomba980-local /tmp/release-nr
cd /tmp/release-nr
svn status
svn add --force .   # first release only; skips ignored files
svn commit -m "Release <version>"
```

The public HTTPS URL is:

```text
https://svn.grimore.org/node-red-contrib-roomba980-local
```

The repository was briefly available as
`node-red-contrib-dorita980-local`; that path has been removed. Use only the
URL above in package metadata and documentation.

Useful SVN properties for the repository root:

```sh
svn propset svn:ignore "node_modules
*.tgz
npm-debug.log*
coverage" .
svn commit -m "Ignore build and dependency artifacts"
```

## 3. Publish to Verdaccio

Verdaccio credentials live in `~/.npmrc`. Publish from the working copy:

```sh
npm publish --registry=https://npm.grimore.org/ --access public
```

`publishConfig.access` is already `public`; the explicit flag keeps the
intent visible for a scoped package.

Verify:

```sh
npm view '@wizardry.steamworks/node-red-contrib-roomba980-local' version --registry=https://npm.grimore.org/
npm view '@wizardry.steamworks/node-red-contrib-roomba980-local' dist.tarball --registry=https://npm.grimore.org/
```

If a release is wrong, publish a new patch version. Do not unpublish a version
that other flows may already have installed.

The earlier package names `node-red-contrib-roomba980-local` and
`node-red-contrib-dorita980-local` are unpublished and must not be republished.
All three names register the same node types (`dorita980Config`, `basic`,
`get`, `set`, `getstatus`), so users who still have an earlier package
installed must remove it. The README explains the upgrade, and the plugin logs
a startup warning if it detects either earlier package next to it.

## 4. Publish to npmjs.com

The public Flow Library requires the package to be published on the public npm
registry under a scoped name. Node-RED's packaging guidelines, updated on
31 January 2022, require a scope for packages first published after that date.
An unscoped name is rejected even when it otherwise follows the
`node-red-contrib-` convention.

The scope is `@wizardry.steamworks`. npm treats the scope exactly like an npm
user or organisation name. Dots are allowed in package names and scopes, so
`@wizardry.steamworks/...` is a valid name. Before publishing, make sure the
`wizardry.steamworks` organisation (or a user of that name) exists on npmjs and
that your account can publish to it; create it at
<https://www.npmjs.com/org/create> if needed. If npm refuses the name with a
dot, create the organisation as `wizardry-steamworks` instead, change `name`
in `package.json`, and update the same references.

```sh
npm login --registry=https://registry.npmjs.org
npm publish --registry=https://registry.npmjs.org --access public
```

`publishConfig.access` in `package.json` is already `public`, but keep the
explicit flag: scoped packages default to private. `prepublishOnly` runs
`npm test` before the upload.

Verify the public registry:

```sh
npm view '@wizardry.steamworks/node-red-contrib-roomba980-local' version --registry=https://registry.npmjs.org/
npm view '@wizardry.steamworks/node-red-contrib-roomba980-local' dist.tarball --registry=https://registry.npmjs.org/
```

Install the public release into a scratch Node-RED user directory:

```sh
mkdir -p /tmp/nr-npmjs-test
cd /tmp/nr-npmjs-test
npm init -y
npm install '@wizardry.steamworks/node-red-contrib-roomba980-local@<version>'
node -e "require('@wizardry.steamworks/node-red-contrib-roomba980-local/dorita980/dorita980.js')"
```

**Do not submit to the Flow Library yet.** The Flow Library reads the package
from the public npm registry. Step 5 can only succeed after `npm view` above
returns the new version from `registry.npmjs.org` and the public install test
works. A package that exists only on Verdaccio, or whose npmjs publish failed,
cannot be added.

### Package name rules

The public name must satisfy all of the following:

* starts with a scope: `@wizardry.steamworks/`;
* uses lowercase, URL-safe characters only;
* has no uppercase letters and no leading `.` or `_`;
* is at most 214 characters, including the scope.

The unscoped part still starts with `node-red-contrib-`, which is not required
for a scoped package but keeps the association with Node-RED. Keep the
`node-red` node mapping and all node types unchanged, so imported flows remain
compatible. The SVN repository name and the internal `dorita980/` directory do
not have to change.

## 5. Submit or refresh the Flow Library listing

Complete step 4 first. The Flow Library does not accept a package that is not
publicly resolvable on npmjs.com.

First submission:

1. Sign in at <https://flows.nodered.org/> with GitHub.
2. Open <https://flows.nodered.org/add/node>.
3. Enter `@wizardry.steamworks/node-red-contrib-roomba980-local` and submit.

Later releases are picked up automatically, but the listing can be refreshed
immediately from the package page with **Request refresh**. The Flow Library
reads the public npm package and its README, so make sure the npmjs release is
the one you want listed.

Requirements checked by the Flow Library:

* the package is published publicly on npmjs.com, not only on Verdaccio;
* `README.md` describing the nodes;
* `node-red` section in `package.json` listing the node files;
* `"node-red"` in the `keywords` array;
* a package name that follows the naming guidelines: a scoped name for
  packages first published after 31 January 2022.

README links to files shipped inside the package must use absolute URLs (for
example the SVN file URL). The Flow Library renders the README without serving
the package contents, so relative links such as `LICENSE` or
`examples/roomba-local.json` return 404 on the node page.

## 6. Post-release checklist

- [ ] `package.json` version and `CHANGELOG.md` agree.
- [ ] `npm test` passes.
- [ ] `npm audit --omit=dev` is clean for a default (firmware 2.x) install.
- [ ] Tarball contains the vendored `dorita980`.
- [ ] SVN commit created and tagged if desired.
- [ ] Verdaccio has the new version.
- [ ] npmjs.com has the new version and `npm view` resolves from
      `registry.npmjs.org`.
- [ ] Public npm install from a clean directory succeeds.
- [ ] Only after the npmjs checks pass: Flow Library listing accepted or
      refreshed.
- [ ] Only the scoped package is published publicly; the earlier unscoped
      `node-red-contrib-roomba980-local` and temporary
      `node-red-contrib-dorita980-local` names remain unpublished.
