# Package upgrades

An upgrade is a change to `jadpo.lock` and `packages/`, reviewed like any
other change, its `surface.jadpo_record` diff included. The review
compares the provider operations and library declarations your app uses,
matched by package, resource and operation with the version ignored. So a
call moved from one version's connection to the next is compared, not
listed as removed and added.

- **Needs a person:** a used operation removed; a used field removed or
  retyped; a new failure on a used operation; a host or credential scheme
  changed; a service's image new or changed; a package installed from a
  third party's git repository.
- **Doesn't need a person:** new operations or optional fields,
  documentation, and changes to operations your app never calls.
- **Shown, and needing a person as a new host:** a new `outbound:` grant
  to a service, and a new connection's hosts, each a `NetworkChange`.
- **A package from git** needs a person (`PackageChange.git_source`)
  unless its repository is under one of `packages:`'s `own_sources:`
  ([Installing safely](/docs/where-packages-come-from.md#installing-safely)).

**What counts as used** is read on the before side, since the agent has
usually fixed the compile error by the time `jadpo check` is judged: the
app's code, outside tests and comments, writing a name through the package
(`Postcodes.uk.parse`) or through a connection to it
(`couriers.bookings.get`), and the types and failures those reach through
their inputs, outputs and fields. A connection the code never writes, or
that `application { }` names elsewhere (`email: { connection: mail }`),
serves the app through a capability, so all its operations count as used.
A provider's hosts and credential scheme count once a connection reaches
the package. A package removed altogether isn't an upgrade.

Each change has its entry in [Acceptances](/docs/acceptances.md), its subject
without the version. A new required input field, a new enum variant, a
failure no longer listed and a changed failure message need nobody: the
compiler stops what they would break, or nothing relied on them.

`jadpo package update <name>` prints this part of the review, and the
[approval report](/docs/reviewing-a-change.md) says each
in plain words. It is the same output as the upgrade plan
[External services](/docs/external-services.md) refers to, not a separate format.