Update README

README.md

@@ -1,23 +1,55 @@
-# Packaging dmpd
+# Packaging device-mapper-persitent-data (AKA dmpd)
 
-This is rust package using *vendor* file for dependencies.
+This is rust package using *vendor* file for dependencies. (Vendor file is an archive of dependencies' sources.)
 
-To build the package following tooling is needed:
+For most of simple fixes, there is nothing special,
+to add a patches simply add them to dist-git,
+add a corresponding `PatchN: 000N-...` lines,
+increase `Release:` or `release_suffix` for Z-stream (or for test build use suffix like `.bzNNNNNN`),
+add to `%changelog`,
+commit,
+push,
+and build the package using `fedpkg build`.
 
-- rust >= 1.35
-- cargo with vendor subcommand (now upstream, included in latest Fedora and RHEL8+)
+Alternatively before committing anything use `fedpkg srpm` and `fedpkg scratch-build --srpm $SRPM [--arches x86_64]` to create a scratch build.
 
-## cargo vendor
+However when building a new version of dmpd or when updating a dependency is
+needed (e.g. because of CVE in the dependency) vendor file
+has to be regenerated.
 
-- run `cargo vendor` in the directory with sources
-- run `tar czf device-mapper-persistent-data-vendor-$VERSION.tar.gz ./vendor`
-- copy the file (if version changed) and run the *fedpkg new-sources* command:
+## Updating vendor file
+
+To build a new version of the package following tooling is needed:
+
+- `rust >= 1.35`
+- `cargo` providing vendor subcommand (now upstream, included in latest Fedora and RHEL8+)
+
+To create the vendor file:
+
+In the upstream directory:
+
+1. Run `cargo vendor` in the directory with upstream sources to create *vendor*
+   directory with sources.
+    - TODO: There is a *cargo-vendor-filterer* project used by *stratisd* to
+      filter out unnecessary dependencies for other operating systems.
+2. Run `tar czf device-mapper-persistent-data-vendor-$VERSION.tar.gz ./vendor` to create a tarball.
+3. Copy the vendor file to dist git directory.
+
+In the dist-git directory:
+
+1. Get the upstream tarball `wget https://github.com/mingnus/thin-merge/archive/v$VERSION.tar.gz`
+2. Update *Source0* and *Source1* to correct values.
+3. Add the tarballs to koji/brew lookaside:
     - `fedpkg new-sources v$VERSION.tar.gz device-mapper-persistent-data-vendor-$VERSION.tar.gz`
-- some dependencies (at the moment only *rio*) are not using upstream from
-  registry, but a patched version. **After** running cargo vendor apply patch
-  *0001-Tweak-cargo.toml-to-work-with-vendor-directory.patch* so build does not
-  try to connect to internet. This dependency is being replaced by supported
-  crate.
+4. You may need to update *0001-Tweak-cargo.toml-to-work-with-vendor-directory.patch* to modify
+   *Cargo.toml* file. Some dependencies (at the moment only *rio*) are not
+   using upstream from registry, but a patched version. With unmodified
+   *Cargo.toml* build would fail as it would try to reach to internet.
+    - NOTE: This patch **MUST NOT** be present in the upstream source directory
+      when running `cargo vendor`.
+    - I apply the patch after step 1, and use `git format-patch HEAD^` to
+      create the patch and add the patch to dist-git directory afterwards.
+    - The work to replace dependency on rio is in progress.
 
 ## TODO/NOTES