# Packaging — unlocked, org-dependent, 2GP managed

Target: Spring '26. Sources: [Second-Generation Managed Packages](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_dev2gp.htm), [Unlocked Packages](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_intro.htm), [`sf package` commands](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_package_commands_unified.htm).

## 1. Choosing the package type

| Type | Namespace | Source of truth | Choose when | The catch |
|---|---|---|---|---|
| **Unlocked package** | Optional (usually none) | Your git repo | Internal org development, a shared design system, a domain module | Admins can still change the metadata in the org; drift is caught by CI, not by the platform |
| **Org-dependent unlocked package** | None | Your git repo, but it compiles against one org | The legacy org's metadata is tangled and the package genuinely cannot build in a clean scratch org | No scratch-org validation, so the safety net you most need is the one you lose. Treat it as a migration step, not a destination |
| **2GP managed package** | Required, permanent | Your git repo, versioned and locked | Distributing to other orgs: AppExchange, an ISV product, or your own multi-org estate | The namespace prefixes every API name forever; upgrades follow managed-package rules; some metadata is not upgradeable |
| **Unpackaged metadata** | — | A directory | Org-specific configuration that is not a reusable unit (page layouts, profiles, the org's own flexipages) | No versioning and no dependency graph — keep it small and deliberate |

Rule of thumb: **one org → unlocked; many orgs or external customers → 2GP managed; neither → unpackaged.** Org-dependent is the escape hatch with a deadline attached.

## 2. Dependency rules that keep a multi-package repo sane

```jsonc
// sfdx-project.json
{
  "packageDirectories": [
    { "path": "packages/design-system", "package": "org-design-system", "versionNumber": "2.4.0.NEXT", "default": false },
    { "path": "packages/sales-orders",  "package": "org-sales-orders",  "versionNumber": "1.9.0.NEXT", "default": true,
      "dependencies": [ { "package": "org-design-system", "versionNumber": "2.4.0.LATEST" } ] }
  ],
  "namespace": "",
  "sourceApiVersion": "66.0"
}
```

- Dependencies point one way: feature packages depend on the design system, never the reverse. A circular dependency means the split is wrong.
- Pin with `.LATEST` during development and to an exact version for a release build, so a promoted version is reproducible.
- Every package has its own CI job: create a version, install it into a fresh scratch org with its dependencies, run its tests. A package that only builds in the big shared sandbox is not a package.
- Metadata that cannot live in a package (profiles, most org settings) stays unpackaged and is applied by the pipeline — see `salesforce-devops`.

## 3. Versioning and promotion

```bash
sf package version create --package org-design-system --installation-key-bypass \
  --code-coverage --wait 60
sf package version promote --package "org-design-system@2.4.0-7"      # released, immutable
sf package install --package "org-design-system@2.4.0-7" --target-org staging --wait 20
```

- Only a **promoted** version can be installed in production, and a promoted version is immutable — bump the patch instead of "just rebuilding".
- Semantic meaning the org can rely on: major = breaking API change to an `@api` property or an exposed Apex method, minor = new components or properties, patch = fixes.
- Keep a changelog per package next to the code, written for the admins and developers who install it, not for the committers.

## 4. Namespaces and the multi-org question

- A namespace is permanent. `mypkg__OrderList` appears in every API name, every SOQL of a subscriber, every integration payload. Take one only when you genuinely distribute across orgs.
- For an internal multi-org estate, weigh the namespace cost against the alternative: separate unlocked packages per org built from one repo, with the differences expressed as metadata rather than as forks.
- Components in a managed package are only accessible outside it when marked `global`/`@api` — decide the public surface before the first release, because removing it later is a breaking change for every subscriber.
- Managed-package components carry the **`lightningCommunity__RelaxedCSP`** consideration for Experience sites and cannot be edited in the subscriber org: the support model has to be part of the decision, not an afterthought.

## 5. Checklist

- [ ] Package type chosen with its reason, and org-dependent has an end date
- [ ] Dependency graph is acyclic and written in `sfdx-project.json`
- [ ] Each package installs and passes its tests in a fresh scratch org in CI
- [ ] Promotion is part of the release, and production installs only promoted versions
- [ ] Public surface (`@api`, `global`) is deliberate and documented
- [ ] Namespace taken only for genuine multi-org or AppExchange distribution
- [ ] Changelog per package, written for installers
