Update README and setup release and publication

.github/workflows/pypi.yml

@@ -0,0 +1,17 @@
+name: Release Package to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build and publish to pypi
+        uses: JRubics/[email protected]
+        with:
+          pypi_token: ${{ secrets.PYPI_PASSWORD }}

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        type: choice
+        description: How to bump the version
+        required: true
+        options:
+          - major
+          - minor
+          - patch
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+            token: ${{ secrets.BOT_ACCESS_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install poetry
+      - run: poetry install --all-extras
+      - name: Configure git
+        run: |
+          git config --global user.name 'Release bot'
+          git config --global user.email '[email protected]'
+          git push
+      - name: bump release version and tag
+        run: |
+          poetry version ${{ github.event.inputs.bump }}
+          export NEW_VERSION=v$(poetry version -s)
+          git commit -am "Bumping to version $NEW_VERSION"
+          git tag -a $NEW_VERSION -m $NEW_VERSION
+      - name: prepatch to the next version
+        run: |
+          poetry version prepatch
+          export NEW_VERSION=v$(poetry version -s)
+          git commit -am "Prepatching to $NEW_VERSION"
+      - name: Push results
+        # See https://www.wearecogworks.com/blog/quick-guide-to-running-sub-workflows-with-github-actions/
+        run: |
+          git push "https://$GITHUB_ACTOR:${{ secrets.BOT_ACCESS_TOKEN }}@github.com/$GITHUB_REPOSITORY.git"
+          git push "https://$GITHUB_ACTOR:${{ secrets.BOT_ACCESS_TOKEN }}@github.com/$GITHUB_REPOSITORY.git" --tags

README.md

@@ -6,12 +6,32 @@
 
 ## N.B. this project is in a pre-release state. There may be breaking changes to all aspects of the tool while some decisions are being made and changed. It is not recommended for use in real projects until the v1.0.0 release. See (TODO milestone) for more info.
 
-## Running `flux`
+## Adding `flux` to your project
 
 ### CLI
 
+``flux`` can be installed for now from Github. For example:
+
+```
+poetry add git+https://github.com/k2bd/flux-migrations.git[postgres]
+```
+
+The project will be properly maintained on PyPI when it's stable. The PyPI version may therefore not be up-to-date at this time.
+
+``flux`` commands can then be listed with ``flux --help``
+
+For example, migrations can be initialized and started with:
+
+```
+flux init postgres
+
+flux new "Initial migration"
+```
+
 ### Docker
 
+(TODO)
+
 ## Writing migrations
 
 ## Use as a library
@@ -25,7 +45,17 @@ This can be particularly useful for testing.
 
 ### Inbuilt backends
 
-(TODO)
+#### Postgres
+
+``flux`` comes packages with a Postgres backend. It maintains information about migrations in a configurable schema and table. Additionally, it uses an advisory lock while migrations are being applied with a configurable index. The available ``[backend]`` configs are:
+
+- ``migrations_schema``
+    - The schema in which to put the migration history table
+    - (default "public")
+- ``migrations_table`` (default "_flux_migrations")
+    - The table used for applied migration history
+- ``migrations_lock_id`` (default 3589 ('flux' on a phone keypad))
+    - The ``pg_advisory_lock`` ID to use while applying migrations
 
 ### Adding a new backend