| Adam Israel | c3e6c2e | 2018-03-01 09:31:50 -0500 | [diff] [blame] | 1 | Syncing Upstream Updates |
| 2 | ======================== |
| Adam Israel | dcdf82b | 2017-08-15 15:26:43 -0400 | [diff] [blame] | 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 |