Develop the repository source

Use this workflow to change the package implementation or evaluate examples that are not yet released.

Note

Create a scratch org for changing the Record Health Check package source. The setup deploys Apex, Lightning Web Components, and Custom Metadata and runs the package’s local Apex tests.

Important

This workflow deploys unpackaged package source into a development org. Do not use it to install or upgrade Record Health Check in a subscriber sandbox or production org. Subscribers install the promoted unlocked package (04t) from Install and verify.

npm run setup creates an installed-package demo. npm run dev:setup deploys unpackaged contributor source. They are different workflows; do not substitute one command for the other.

Use this guide for source development and evaluation. The package project is in packages/record-health-check/. If the goal is to evaluate the installed package as an administrator or user, follow Create a demo scratch org instead.

Before changing how a Check evaluates data, read Check and Check Set outcome verification. New behavior is incomplete until its passing, failing, and applicable skipped or unable-to-check results are executable in Salesforce and protected by the source gates.

Prerequisites

Before you start:

• Git
• Salesforce CLI (sf) installed and on your PATH, using the version in the toolchain configuration
• A Dev Hub org you can authenticate (example alias: my-dev-hub)
• Node.js with npm, using the major version in the toolchain configuration

Clone the repository, install its pinned dependencies, authenticate the Dev Hub, and verify the required Salesforce CLI version:

git clone https://github.com/gkolan/record-health-check.git
cd record-health-check
npm ci
sf org login web --set-default-dev-hub --alias my-dev-hub
npm run check:toolchain

The final command verifies your tools against the repository toolchain configuration. If it reports a mismatch, install the required version before continuing.

Step 1: Create the contributor org

From the repository root, run:

npm run dev:setup -- --dev-hub my-dev-hub --alias rhc-dev

Before creating the org, the command confirms that the Dev Hub has both an available active scratch org and an available scratch-org creation for the day. It then creates a seven-day scratch org. The command refuses to overwrite an existing alias, so choose a new alias when rhc-dev already exists.

What success looks like:

Milestone	Expected result
Scratch org created	Alias rhc-dev (or the alias you chose) is Active
Package source deployed	packages/record-health-check/force-app is in the org, including Record Health Check Diagnostics Viewer
Administrator access assigned	Record Health Check Admin is assigned to the setup user and already includes diagnostic access
Integration fixtures deployed	packages/record-health-check/integration-tests is in the org for maintainer gates
Local tests ran	Package RunLocalTests completed during the package-source deploy

To test diagnostics as a non-admin, assign Record Health Check Diagnostics Viewer alongside Card User or User, then enable Show Diagnostics on the selected Check Set. Follow the scratch-org permission steps. The data-seeding command does not assign permissions.

This command does not install the public 04t subscriber package.

Rollback for this workflow means deleting the exact disposable scratch org alias after preserving any needed test evidence. It never means deleting source or packages from a sandbox or production org.

Step 2: Rerun package tests

After changing Apex or metadata, deploy those changes to rhc-dev, then rerun local tests in the same org. The command below runs every local Apex test and requests code coverage; it does not deploy unsaved source changes.

npm run dev:test -- --alias rhc-dev

Seed the current-source Acme demo

Contributor and portable-test orgs deploy source, so they do not run the installed-package demo setup automatically. Seed and verify the documented Acme hierarchy in either a namespaced or no-namespace source scratch org with:

npm run demo:setup-source -- --alias rhc-dev

The command detects the source namespace, restores Jordan Blake as Acme’s inactive owner, and seeds both the Acme Builder Guide and the dedicated readiness scenarios. It verifies all 49 active Checks across the four example Check Sets. Every active example Check is exercised with both a passing and a needs-review record; applicable skipped and unable-to-check outcomes are exercised as well. The Builder Guide retains 7 Passed, 17 Failed, 0 Skipped, and 1 Unable to Check for Acme. The complete dataset contains eight Accounts, 51 Contacts, 19 Opportunities, 12 Contact Roles, six Tasks, 20 Cases, one Campaign, and one Product with four Opportunity Line Items.

To verify the current data without reseeding:

npm run demo:verify-source -- --alias rhc-dev

See readiness scenarios and cleanup for the expected results, record markers, and safe removal order.

Optional: Prove portable no-namespace source deployment

Use this contributor check when you deliberately support unpackaged source outside the rhc package. It deploys the same force-app into a one-day scratch org with no namespace and runs local Apex tests. It is not a blocking 2GP release shape because the released package always uses rhc.

npm run dev:test-no-namespace -- --dev-hub my-dev-hub --alias rhc-portable

Check	Command	Org shape
Namespaced package development	npm run dev:setup	Uses the nested project’s rhc namespace
No-namespace portable deploy	npm run dev:test-no-namespace	Creates a scratch org with --no-namespace

Manual package-project commands

When you need finer control, work from the nested project:

cd packages/record-health-check

sf project deploy start \
  --manifest manifest/package.xml \
  --target-org rhc-dev \
  --test-level RunLocalTests \
  --wait 30

The manifest deploy runs the package’s local Apex tests but does not deploy the separate integration-tests directory. Deploy those test fixtures only when the change requires the maintainer integration gates.

Keep integration-tests/ out of subscriber installs. That directory contains maintainer test fixtures, not package metadata. See the integration-tests README.

Repository checks for contributors

Package contributors must keep the same Qualified API Name behavior in Apex, Flow, Lightning, tests, and documentation. After changing selection logic or installed examples, run:

npm run check:configuration-identity
npm run check:package-boundary
npm run check:agent-tool-contract

The package source is under packages/record-health-check/force-app. Test-only metadata under packages/record-health-check/integration-tests and subscriber-app is not included in a normal installation.

Documentation and static-site changes

Documentation is maintained as Markdown under docs/ and published as generated HTML. Run npm run check:docs:site for every documentation or site-renderer change. When conversion, navigation, global components, global styles, responsive layout, Astro, or Starlight can affect multiple pages, also run npm run audit:docs:render and inspect every desktop and mobile screenshot. Follow Static-site rendering and visual verification for the required evidence, targeted retry rules, and completion checklist.

Step 4: Delete scratch orgs when testing is complete

Delete every scratch org created for the change after its evidence is no longer needed:

sf org delete scratch --target-org rhc-dev --no-prompt
sf org delete scratch --target-org rhc-portable --no-prompt

Replace the aliases when different names were supplied. These commands delete the Salesforce scratch orgs; they do not delete repository files. Do not delete a shared org or an org that this workflow did not create.

Remove development source from a retained development org

If Record Health Check was source-deployed during contributor development, remove the same manifest that installed it. Run these commands from packages/record-health-check/ or pass the full manifest path from the repository root:

cd packages/record-health-check

sf project delete source \
  --manifest manifest/package.xml \
  --target-org <org-alias> \
  --check-only

Review the --check-only (dry-run) output before removing the check. Confirm the manifest does not include anything the org still needs, then run the deletion:

sf project delete source \
  --manifest manifest/package.xml \
  --target-org <org-alias>

Do not run a bare deletion without a manifest. Deleting by manifest keeps the operation scoped to Record Health Check’s own components.

This alternative applies only to contributor development orgs. An org that used the public package installer should follow the package uninstall guide.

Windows and shell notes

npm run dev:setup, npm run dev:test, and npm run dev:test-no-namespace use Node and work the same on Windows, macOS, and Linux. You still need the Salesforce CLI installed and authenticated to a Dev Hub.

Pass the Dev Hub with --dev-hub, which behaves the same in bash, zsh, PowerShell, and cmd. The DEV_HUB_ALIAS environment variable is still honoured, but the VAR=value command prefix form is bash/zsh-only and does nothing on Windows:

npm run dev:setup -- --dev-hub my-dev-hub --alias rhc-dev

On Windows, prefer PowerShell, cmd, or Git Bash for these npm entry points. Do not call the Windows sf CLI from WSL bash.

Shell scripts under scripts/*.sh (for example display-format fixtures) remain bash/zsh. On Windows, run those from Git Bash, or use the Node npm run entry points documented on this page when both options exist.

Troubleshooting

Symptom	What to check
An org already uses alias '…'	Confirm which org owns the alias. Choose a new --alias, or delete the old scratch org only when this work created it and it is no longer needed.
Scratch-org capacity is insufficient	Reuse a suitable contributor org, delete an owned org that is no longer needed, or wait for the daily limit to reset
Toolchain check reports another CLI version	Install the exact version shown in config/toolchain.json, then rerun npm run check:toolchain
Deploy fails on currency field planner tests	In a multi-currency org, CurrencyIsoCode can appear in the field plan. Update a test that assumes only Id to reflect that org shape.
sf not found on Windows	Confirm the Salesforce CLI install and that your shell session can resolve sf
Need the subscriber demo instead	Use npm run setup and Create the demo scratch org
Acme Corporation is missing from a source org	Run npm run demo:setup-source -- --alias <source-org-alias>

Next steps

• Follow the documentation quality and accuracy standard when editing any page in docs
• Review the local gates in Contributing before you open a PR
• Read Package testing and upgrades for test ownership and subscriber upgrade behavior
• Follow Releasing when you are ready to create a package version