From 48b5b572ca8fe9d9859a571f604c360f17adf956 Mon Sep 17 00:00:00 2001
From: Nick Coghlan <ncoghlan@gmail.com>
Date: Oct 23 2017 09:32:50 +0000
Subject: Update README to reflect current status


---

diff --git a/README.md b/README.md
index ed292b8..dc2f16c 100644
--- a/README.md
+++ b/README.md
@@ -6,37 +6,68 @@ fedpkg and mbs-build).
 
 Currently, this consists of:
 
-* `fedmod rpm2module`: generates a draft modulemd file based on existing RPM
-  name.
+* `python -m fedmod rpm2module`: generates a draft modulemd file based on
+  the given RPM name (multiple RPM names can be given, but the resulting
+  draft module will lack any descriptive metadata in that case)
+* `python -m fedmod metadata`: download the F27 Modular Server repository
+  metadata needed to generate draft module definitions
 
 ## Project status
 
-`fedmod` is pre-release software originally written to work with the F26 Boltron
-prototype, and doesn't currently pass its own self tests without appropriate
-prior configuration of the test system.
+`fedmod` is not yet released, but can already generate basic draft modules from
+a local development checkout:
 
-It's in the process of being updated to have a clearer development focus,
-and to work with the native modularity metadata provided in Fedora 27.
+    $ pipenv run python -m fedmod rpm2module samba
+
+This will generate a draft `modulemd` file called `samba.yaml` in the current
+directory.
+
+See the local development instructions below for info on setting up the
+execution environment with `pipenv`.
 
 ## Modulemd creation
 
-`fedmod rpm2module` creates a modulemd file from the given package names.
-Output is written as `modulemd-output.yaml` when multiple packages are given
-as input, and `<input-package-name>.yaml` when a single package is given.
+`python -m fedmod rpm2module [RPM NAMES]` creates a modulemd file from the
+given package names. Output is written as `<input-package-name>.yaml` when a
+single package name is given, and `modulemd-output.yaml` otherwise.
+
+The following metadata is currently used as input to the draft module generation
+process:
+
+* Module definitions and package dependencies are pulled from the modular Fedora
+  Bikeshed repository, with the metadata being downloaded for local use via
+  the `python -m fedmod metadata` command
+
+* Descriptive metadata is taken from the system running `fedmod`. Due to this,
+  `fedmod` currently only supports Fedora 26+. (This will be fixed to use
+  the same repository metadata as everything else)
+
+Module dependencies currently err on the side of making the generated modules
+smaller by permitting generated modules to depend on packages that aren't
+listed as part of the public API of other modules. This reflects the fact that
+those transitive dependencies are typically the reason for the lower level
+modules appearing in the dependency set in the first place, as well as the fact
+that true dependency isolation will start being enforced once modules begin
+including opaque container images, such that only the client libraries are
+installed into shared environments.
 
 ## Local development
 
 ### Runtime dependencies
 
-The currently preferred means of installation is local installation with pip.
+The currently preferred means of dependency management is with `pipenv`:
 
-    $ pip install .
+    $ pipenv --three --site-packages
+    $ PIP_IGNORE_INSTALLED=1 pipenv install --dev
 
 This will pull in the required Python level dependencies from PyPI.
 
-Some dependencies aren't currently available from PyPI, and will need to be
-installed system-wide (exact list TBD, but includes at least dnf and libsolv's
-Python bindings).
+Some dependencies aren't currently available from PyPI, and hence need to be
+installed system-wide:
+
+    $ sudo dnf install python3-dnf python3-solv
+
+
 
 ### How to run tests