# Security update: update a single crate

This approach is suitable for security updates as it doesn't require a change
to the upstream version number. However, it'll make for a very ugly patch, and
might not work if one of the crate has some changes that the quilt patch format
cannot represent.

For commodity, it has been wrapped up in a small shell script that will create a patch
update-$crate-$version.patch and insert it in the series file.

Note that the script might fail at the last stage, indicating that the new
crates conflict with our patch removing unused dependencies. You'll have to
amend said patch manually.

```sh
debian/update-crate.sh openssl 0.10.55
```

# Normal upstream update: refresh the vendor tarball

First, update the package as usual, including the new d/changelog entry.

Then update recreate the vendor tarball:
```sh
debian/rules vendor-tarball
```

## Optional:
In case the processing/download of the crates takes too long (due to the
amount or size of the crates) it can be temporarily accelerated by using
`sparse-registry`.
Modify the `cargo vendor` line in `debian/rules` like this:
`cargo vendor -Z sparse-registry --manifest-path rust/Cargo.toml \
$(CARGO_VENDOR_DIR)`
then call:
`export CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse && \
debian/rules vendor-tarball`,
but revert back this change once the vendor-tarball was successfully recreated.

## Hints:
- In case of changes in the rust code or the crates, there is a high chance
  that `debian/patches/vendor-remove-unused-deps.patch` needs to be adjusted.
- With `cargo -Z sparse-registry tree` one can now get an overview of the
  vendored crates and their dependencies that are in use and that were
  downloaded and packed.
- To get an overview about the size of each individual crate, incl. the overall
  size, one can run `du -hd2 rust-vendor  | grep -v '/src' | sort -h`.
  The output should be compared to the output for the previous package version.
  (Consider redirecting the outputs and verify their diff.)
- In case of significant changes in size and amount, consider doing further
  optimizations and check for example if all crates are really needed for Ubuntu,
  some may be needed for Windows systems only.
