modules/libjuju/docs/upstream-updates/index.rst

   1 Syncing Upstream Updates
   2 ========================
   3
   4 Updating the facade and definitions code generated from the schema
   5 to reflect changes in upstream Juju consists of two steps:
   6
   7 * Creating a new `schemas-juju-<version>.json` file from the Juju code-base
   8 * Generating the libjuju Python code from that schema
   9
  10 Rarely, you may also have to add or update an override.
  11
  12
  13 Creating a Schema File
  14 ----------------------
  15
  16 First, you will need to fetch SchemaGen_ and a copy of the Juju source.
  17 Once your copy of the Juju source is at the version you want to update to
  18 (probably the `develop` branch, or a release tag) and you have updated
  19 and reinstalled SchemaGen to reflect those changes, you just need to send
  20 the output into a file in the libjuju repository:
  21
  22 .. code:: bash
  23
  24   schemagen > juju/client/schemas-juju-2.2-rc1.json
  25
  26 The version number you use in the filename should match the upstream
  27 version of Juju.  You should then also move the `latest` pointer to
  28 the new file:
  29
  30 .. code:: bash
  31
  32   rm juju/client/schemas-juju-latest.json
  33   ln -s schemas-juju-2.2-rc1.json juju/client/schemas-juju-latest.json
  34
  35
  36 Generating the Python Code
  37 --------------------------
  38
  39 Once you have a new schema file, you can update the Python code
  40 using the `client` make target:
  41
  42 .. code:: bash
  43
  44   make client
  45
  46 You should expect to see updates to the `juju/client/_definitions.py` file,
  47 as well as one or more of the `juju/client/_clientX.py` files, depending on
  48 which facades were touched.
  49
  50
  51 Overrides
  52 ---------
  53
  54 It should be quite rare, but occasionally the generated Python code does
  55 not capture all of the logic needed to properly parse the output from the API
  56 or may otherwise need some small amount of tweaking.  This is what the
  57 `juju/client/overrides.py` file is for.  An example of this is the `Number`
  58 type, which isn't standard JSON and must be parsed slightly differently.
  59
  60 At the top of that file are two lists, `__all__` and `__patches__`.  The
  61 former replaces entire class implementations, while the latter patches
  62 the attributes of the override classes into the matching generated class,
  63 leaving the rest of the generated class untouched.
  64
  65
  66 .. _SchemaGen: https://github.com/juju/schemagen