merge conflicts

.github/workflows/cargo_publish.yml

@@ -0,0 +1,83 @@
+name: Cargo publish or validate
+
+on:
+  pull_request:
+    branches:
+      - main
+      - "release/[0-9]+.[0-9]+"
+  push:
+    branches:
+      - 'main'
+      - 'release/[0-9]+.[0-9]+'
+
+jobs:
+  find_directories:
+    name: Find crates that changed
+    runs-on: ubuntu-20.04
+    outputs:
+      changed_crates: ${{ steps.find_directories.outputs.build_matrix }}
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+      - name: Find directories including Cargo.toml that changed
+        id: find_directories
+        uses: ./.github/actions/find-changed-directories
+        with:
+          contains_the_file: Cargo.toml
+          # If the branch does not exist, then it will not
+          # filter any directories containing the file.
+          # This allows for filtering out unchanged directories
+          # in a pull request, and using all directories on the release
+          # or main branches.
+          changed_relative_to_ref: origin/${{ github.base_ref || 'not-a-branch' }}
+
+
+  cargo_publish:
+    # On a pull request, this is validating that the version
+    # is not already published to crates.io, and on a push to
+    # main or release branches, it is publishing if the version
+    # does not exist, ignoring if the version is already
+    # published.
+    name: Cargo publish or validate
+    runs-on: ubuntu-20.04
+    needs:
+      - find_directories
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.find_directories.outputs.changed_crates) }}
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+      - name: Determine which flags to use on cargo publish
+        id: cargo_flags
+        run: |
+          set -x
+          BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
+          if [ "${BRANCH_NAME}" == "main" ]; then
+            echo "dry_run=false" >> $GITHUB_OUTPUT
+            echo "fail_if_version_published=false" >> $GITHUB_OUTPUT
+          elif [[ "${BRANCH_NAME}" == release/* ]]; then
+            echo "dry_run=false" >> $GITHUB_OUTPUT
+            echo "fail_if_version_published=false" >> $GITHUB_OUTPUT
+          else
+            echo "dry_run=true" >> $GITHUB_OUTPUT
+            echo "fail_if_version_published=true" >> $GITHUB_OUTPUT
+          fi
+      - uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: ${{ matrix.name }}
+          workspaces: |
+            ${{ matrix.path }}
+          # Additional directories to cache
+          cache-directories: |
+            /home/runner/.pgrx
+      - uses: ./.github/actions/pgx-init
+        with:
+          working-directory: ${{ matrix.path }}
+      - name: Publish or validate
+        uses: ./.github/actions/publish-crate
+        with:
+          working-directory: ${{ matrix.path }}
+          dry-run: ${{ steps.cargo_flags.outputs.dry_run }}
+          fail-if-version-published: ${{ steps.cargo_flags.outputs.fail_if_version_published }}
+          cargo-registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}

.github/workflows/crate_ci.yml

@@ -10,7 +10,7 @@ on:
     branches:
      - main
     paths:
-      - '.github/workflows/pgmq.yml'
+      - '.github/workflows/crate_ci.yml'
       - 'core/**'
   push:
     branches:
@@ -56,21 +56,3 @@ jobs:
         run: cargo sqlx prepare --check
       - name: teardown
         run: make test.cleanup
-
-  publish:
-    # only run when tag release
-    if: startsWith(github.ref, 'refs/tags/')
-    name: Publish Crate & Extension
-    runs-on: ubuntu-22.04
-    needs: [lint, tests]
-    steps:
-      - uses: actions/checkout@v2
-      - name: Install Rust stable toolchain
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-      - uses: Swatinem/rust-cache@v2
-      - name: publish
-        env:
-          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
-        run: cargo publish

.github/workflows/extension_ci.yml

@@ -9,10 +9,12 @@ on:
   pull_request:
     branches:
       - main
-
   push:
     branches:
       - main
+  release:
+    types: 
+      - created
 
 jobs:
   lint:
@@ -76,8 +78,9 @@ jobs:
           cargo pgrx test ${pg_version}
 
   publish:
-    # only publish off main branch
-    if: github.ref == 'refs/heads/main'
+    # only publish on tagged release events
+    # if: github.ref == 'refs/heads/main'
+    if: startsWith(github.ref, 'refs/tags/')
     name: trunk publish
     runs-on: ubuntu-22.04
     steps:

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Postgres Message Queue (PGMQ)
+# Contributing to Postgres Message Queue (PGMQ)
 
 ## Installation
 
@@ -8,44 +8,68 @@ The fastest way to get started is by running the Tembo docker image, where PGMQ
 docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 quay.io/tembo/pgmq-pg:latest
 ```
 
-# Development
+## Building from source
 
-Setup `pgrx`.
+PGMQ is written as a Rust extension and requires [pgrx](https://github.com/pgcentralfoundation/pgrx).
+
+To build pgmq from source, you need
+* A toolchain capable of building Postgres
+* Rust toolchain
+* [pg_partman](https://github.com/pgpartman/pg_partman).
+
+Once you have those pre-requisites, you need to setup `pgrx`.
 
 ```bash
-cargo install --locked cargo-pgrx
-cargo pgrx init
+cargo install --locked cargo-pgrx --version 0.9.8
 ```
 
-Then, clone this repo and change into this directory.
+Clone the repo and change into the directory.
 
 ```bash
-git clone git@https://github.com/tembo-io/pgmq.git
+git clone https://github.com/tembo-io/pgmq.git
 cd pgmq
 ```
 
-### Setup dependencies
+After this point, the steps differ slightly based on if you'd like to build
+and install against an existing Postgres setup or develop against pgrx managed
+development environment (which installs and allows you to test against multiple
+Postgres versions).
 
-Install:
-- [pg_partman](https://github.com/pgpartman/pg_partman), which is required for partitioned tables.
+### Install to a pre-existing Postgres
 
+Initialize `cargo-pgrx`, and tell it the path to the your `pg_config`. For example,
+if `pg_config` is on your `$PATH` and you have Postgres 15, you can run:
 
-Update postgresql.conf in the development environment.
+```bash
+cargo pgrx init --pg15=`which pg_config`
 ```
-#  ~/.pgrx/data-14/postgresql.conf
-shared_preload_libraries = 'pg_partman_bgw'
+Then, to install the release build, you can simply run:
+```
+cargo pgrx install --release
 ```
 
+### Install against pgrx managed Postgres (Recommended for Development)
 
-Run the dev environment
+Initialize `cargo-pgrx` development environment:
+
+```bash
+cargo pgrx init
+```
+
+**Note**: Make sure you build and install `pg_partman` against the postgres installation
+you want to build against (`PG_CONFIG` in `~/.pgrx/PG_VERSION/pgrx-install/bin/pg_config`
+and `PGDATA` in `/Users/samaysharma/.pgrx/data-PG_MAJOR_VERSION`)
+
+Then, you can use the run command, which will build and install the extension
+and drop you into psql:
 
 ```bash
 cargo pgrx run pg15
 ```
 
-Create the extension
+Finally, you can create the extension and get started with the example in the [README.md](README.md).
 
-```pql
+```psql
 CREATE EXTENSION pgmq cascade;
 ```
 
@@ -56,3 +80,7 @@ Run this script to package into a `.deb` file, which can be installed on Ubuntu.
 ```
 /bin/bash build-extension.sh
 ```
+
+# Releases
+
+PGMQ Postgres Extension releases are automated through a [Github workflow](https://github.com/tembo-io/pgmq/blob/main/.github/workflows/extension_ci.yml). The compiled binaries are publish to and hosted at [pgt.dev](https://pgt.dev). To create a release, create a new tag follow a valid [semver](https://semver.org/), then create a release with the same name. Auto-generate the release notes and/or add more relevant details as needed. See subdirectories for the [Rust](https://github.com/tembo-io/pgmq/tree/main/core) and [Python](https://github.com/tembo-io/pgmq/tree/main/tembo-pgmq-python) SDK release processes.