diff --git a/.github/workflows/ci-pypi-deploy.yml b/.github/workflows/ci-pypi-deploy.yml
new file mode 100644
index 0000000..00f3101
--- /dev/null
+++ b/.github/workflows/ci-pypi-deploy.yml
@@ -0,0 +1,24 @@
+name: package-release
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+     - main
+  release:
+    types:
+      - published
+
+jobs:
+  build:
+    name: build and upload release to pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+      - uses: casperdcl/deploy-pypi@v2
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+          pip: wheel -w dist/ --no-deps .
+          upload: ${{ github.event_name == 'release' && github.event.action == 'published' }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..fe7a799
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v0.1.0](https://github.com/mllam/weather-model-graphs/releases/tag/v0.1.0)
+
+First tagged release of `weather-model-graphs` which includes functionality to
+create three graph archetypes (Keisler nearest-neighbour, GraphCast multi-range
+and Oskarsson hierarchical graphs) deliniating the different connectivity
+options, background on graph-based data-driven models, 2D plotting utilities,
+JupyterBook based documentation. In this version the graph assumes grid
+coordinates are Cartesian coordinates.
diff --git a/README.md b/README.md
index 1bad217..f6bead5 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 # weather-model-graphs
 
-[![linting](https://github.com/mllam/weather-model-graphs/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/mllam/weather-model-graphs/actions/workflows/pre-commit.yml) [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://mllam.github.io/weather-model-graphs)
+[![tests](https://github.com/mllam/weather-model-graphs/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/mllam/weather-model-graphs/actions/workflows/ci-tests.yml) [![linting](https://github.com/mllam/weather-model-graphs/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/mllam/weather-model-graphs/actions/workflows/pre-commit.yml) [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://mllam.github.io/weather-model-graphs)
 
-`weather-model-graphs` is a package for creating, visualising and storing message-passing graphs for data-driven weather models.
+`weather-model-graphs` is a package for creating, visualising and storing graphs used in message-passing graph-based data-driven weather models.
 
 The package is designed to use `networkx.DiGraph` objects as the primary data structure for the graph representation right until the graph is to be stored on disk into a specific format.
 This makes the graph generation process modular (every step outputs a `networkx.DiGraph`), easy to debug (visualise the graph at any step) and allows output to different file-formats and file-structures to be easily implemented. More details are given in the [background](https://mllam.github.io/weather-model-graphs/background.html) and [design](https://mllam.github.io/weather-model-graphs/design.html) section of the online [documentation](https://mllam.github.io/weather-model-graphs/).
@@ -10,10 +10,48 @@ This makes the graph generation process modular (every step outputs a `networkx.
 
 ## Installation
 
+If you simply want to install and use `weather-model-graphs` as-is you can install the most recent release directly from pypi with pip
+
+```bash
+python -m pip install weather-model-graphs
+```
+
+If you want to be able to save to pytorch-geometric data-structure used in
+[neural-lam](https://github.com/mllam/neural-lam) then you will need to install
+pytorch and pytorch-geometric too. This can be done by with the `pytorch`
+optional extra in `weather-model-graphs`:
+
+```bash
+python -m pip install weather-model-graphs[pytorch]
+```
+
+This will install the CPU version of pytorch by default. If you want to install
+a GPU variant you should [install that
+first](https://pytorch.org/get-started/locally/) before installing
+`weather-model-graphs`.
+
+
+## Developing `weather-model-graphs`
+
+The easiest way to work on developing `weather-model-graphs` is to fork the [main repo](https://github.com/mllam/weather-model-graphs) under your github account, clone this repo locally, install [pdm](https://pdm-project.org/en/latest/), create a venv with pdm and then install `weather-model-graphs` (and all development dependencies):
+
 ```
-pdm install
+git clone https://github.com/<your-github-username>/weather-model-graphs
+cd weather-model-graphs
+pdm venv create
+pdm use --venv in-project
+pdm install --dev
 ```
 
+All linting is handeled with [pre-commit](https://pre-commit.com/) which you can ensure automatically executes on all commits by installing the git hook:
+
+```bash
+pdm run pre-commit install
+```
+
+Then branch, commit, push and create a pull-request!
+
+
 ### pytorch support
 
 cpu only: