feat: first release under versioning standard

.env.example

@@ -6,6 +6,10 @@ POSTGRES_DB=ocotilloapi_dev
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 
+# PYGEOAPI
+PYGEOAPI_POSTGRES_PASSWORD=your_password
+PYGEOAPI_POSTGRES_USER=your_username
+
 # Connection pool configuration for parallel transfers
 # pool_size: number of persistent connections to maintain
 # max_overflow: additional connections allowed during peak usage

.github/app.template.yaml

@@ -15,6 +15,7 @@ handlers:
 env_variables:
   MODE: "production"
   ENVIRONMENT: "${ENVIRONMENT}"
+  APP_VERSION: "${APP_VERSION}"
   DB_DRIVER: "cloudsql"
   CLOUD_SQL_INSTANCE_NAME: "${CLOUD_SQL_INSTANCE_NAME}"
   CLOUD_SQL_DATABASE: "${CLOUD_SQL_DATABASE}"

.github/workflows/CD_production.yml

@@ -2,10 +2,13 @@ name: CD (Production)
 
 on:
   push:
-    branches: [production]
+    tags:
+      - 'v*.*.*'        # GA releases: v1.0.0, v1.4.2
+      - 'v*.*.*-*'      # SemVer pre-releases: v1.0.0-rc.1
+      - 'v*.*.*[a-z]*'  # PEP 440 pre-releases: v1.0.0rc1, v1.0.0b2 (release-please-python form)
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
     production-deploy:
@@ -15,7 +18,7 @@ jobs:
 
         steps:
         - name: Check out source repository
-          uses: actions/checkout@v6.0.2
+          uses: actions/checkout@v6.0.3
           with:
             fetch-depth: 0
 
@@ -66,6 +69,7 @@ jobs:
 
         - name: Render App Engine configs
           env:
+            APP_VERSION: ${{ github.ref_name }}
             ENVIRONMENT: "production"
             CLOUD_SQL_INSTANCE_NAME: "${{ secrets.CLOUD_SQL_INSTANCE_NAME }}"
             CLOUD_SQL_DATABASE: "${{ vars.CLOUD_SQL_DATABASE }}"
@@ -141,15 +145,3 @@ jobs:
         - name: Remove rendered configs
           run: |
             rm app.yaml
-
-        # Use PR author's username as git user name
-        - name: Set up git user
-          run: |
-            git config --global user.name "${{ github.actor }}"
-            git config --global user.email "${{ github.actor }}@users.noreply.github.com"
-
-        # ":" are not alloed in git tags, so replace with "-"
-        - name: Tag commit
-          run: |
-            git tag -a "production-deploy-$(date -u +%Y-%m-%d)T$(date -u +%H-%M-%S%z)" -m "production gcloud deployment: $(date -u +%Y-%m-%d)T$(date -u +%H:%M:%S%z)"
-            git push origin --tags

.github/workflows/CD_staging.yml

@@ -15,7 +15,7 @@ jobs:
 
         steps:
         - name: Check out source repository
-          uses: actions/checkout@v6.0.2
+          uses: actions/checkout@v6.0.3
           with:
             fetch-depth: 0
 
@@ -66,6 +66,7 @@ jobs:
 
         - name: Render App Engine configs
           env:
+            APP_VERSION: "${{ github.ref_name }}-${{ github.sha }}"
             ENVIRONMENT: "staging"
             CLOUD_SQL_INSTANCE_NAME: "${{ secrets.CLOUD_SQL_INSTANCE_NAME }}"
             CLOUD_SQL_DATABASE: "${{ vars.CLOUD_SQL_DATABASE }}"

.github/workflows/CD_testing.yml

@@ -15,7 +15,7 @@ jobs:
 
         steps:
         - name: Check out source repository
-          uses: actions/checkout@v6.0.2
+          uses: actions/checkout@v6.0.3
           with:
             fetch-depth: 0
 
@@ -66,6 +66,7 @@ jobs:
 
         - name: Render App Engine configs
           env:
+            APP_VERSION: "${{ github.ref_name }}-${{ github.sha }}"
             ENVIRONMENT: "staging"
             CLOUD_SQL_INSTANCE_NAME: "${{ secrets.CLOUD_SQL_INSTANCE_NAME }}"
             CLOUD_SQL_DATABASE: "${{ vars.CLOUD_SQL_DATABASE }}"

.github/workflows/format_code.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out source repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
       - name: Set up Python environment - 3.12
         uses: actions/setup-python@v6.2.0
         with:
@@ -34,7 +34,7 @@ jobs:
       contents: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v6.0.2
+      - uses: actions/checkout@v6.0.3
         with:
           ref: ${{ github.head_ref }}
       - uses: psf/black@stable

.github/workflows/hotfix-start.yml

@@ -0,0 +1,90 @@
+name: hotfix-start
+
+# Creates a hotfix branch off a release tag per the Data Services Versioning
+# Standard §10. Workflow:
+#   1. Run this workflow (optionally pin base_tag; default = latest v*.*.*).
+#   2. Push fix commit(s) to the new hotfix/vX.Y.(Z+1) branch via PR.
+#   3. release-please opens a Release PR on the hotfix branch.
+#   4. Merge it -> tag vX.Y.(Z+1) -> CD (Production) deploys.
+#   5. Open a forward-merge PR from hotfix/vX.Y.(Z+1) back into production.
+
+on:
+  workflow_dispatch:
+    inputs:
+      base_tag:
+        description: 'Release tag to branch from (e.g. v1.4.2). Empty = latest v*.*.* tag.'
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  create-hotfix-branch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.3
+        with:
+          fetch-depth: 0
+
+      - name: Resolve base tag
+        id: base
+        run: |
+          BASE="${{ inputs.base_tag }}"
+          if [ -z "$BASE" ]; then
+            BASE="$(git tag --list 'v*.*.*' --sort=-v:refname | head -n1)"
+          fi
+          if [ -z "$BASE" ]; then
+            echo "No release tag found (expected v*.*.* tags)." >&2
+            exit 1
+          fi
+          if ! git rev-parse -q --verify "refs/tags/$BASE" >/dev/null; then
+            echo "Tag $BASE not found in repo." >&2
+            exit 1
+          fi
+          echo "tag=$BASE" >> "$GITHUB_OUTPUT"
+
+      - name: Compute next PATCH version + branch name
+        id: next
+        run: |
+          BASE="${{ steps.base.outputs.tag }}"
+          VER="${BASE#v}"
+          IFS='.' read -r MAJ MIN PAT <<<"$VER"
+          if ! [[ "$MAJ" =~ ^[0-9]+$ && "$MIN" =~ ^[0-9]+$ && "$PAT" =~ ^[0-9]+$ ]]; then
+            echo "Base tag $BASE is not strict SemVer vX.Y.Z." >&2
+            exit 1
+          fi
+          NEXT_VER="${MAJ}.${MIN}.$((PAT+1))"
+          BRANCH="hotfix/v${NEXT_VER}"
+          echo "version=${NEXT_VER}" >> "$GITHUB_OUTPUT"
+          echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+      - name: Guard against existing branch
+        run: |
+          if git ls-remote --exit-code --heads origin "${{ steps.next.outputs.branch }}" >/dev/null 2>&1; then
+            echo "Branch ${{ steps.next.outputs.branch }} already exists on origin. Aborting." >&2
+            exit 1
+          fi
+
+      - name: Create + push hotfix branch
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "${{ steps.next.outputs.branch }}" "${{ steps.base.outputs.tag }}"
+          git push origin "${{ steps.next.outputs.branch }}"
+
+      - name: Summary
+        run: |
+          {
+            echo "### Hotfix branch ready"
+            echo ""
+            echo "- Base tag: \`${{ steps.base.outputs.tag }}\`"
+            echo "- New branch: \`${{ steps.next.outputs.branch }}\`"
+            echo "- Target version: \`v${{ steps.next.outputs.version }}\`"
+            echo ""
+            echo "Next steps:"
+            echo "1. Open a fix PR targeting \`${{ steps.next.outputs.branch }}\` (Conventional Commit title, \`fix:\` prefix)."
+            echo "2. After merge, release-please will open a Release PR on the hotfix branch."
+            echo "3. Merge the Release PR -> tag \`v${{ steps.next.outputs.version }}\` -> CD (Production) deploys."
+            echo "4. Open a forward-merge PR \`${{ steps.next.outputs.branch }}\` -> \`production\`."
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/jira_codex_pr.yml

@@ -41,7 +41,7 @@ jobs:
     timeout-minutes: 60
     steps:
       - name: Checkout
-        uses: actions/checkout@0c366fd6a839edf440554fa01a7085ccba70ac98 # v4
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
         with:
           fetch-depth: 0
 

.github/workflows/pr-title-lint.yml

@@ -0,0 +1,38 @@
+name: pr-title-lint
+
+# Enforces Conventional Commits on PR titles so squash-merged commits drive
+# release-please correctly. See Data Services Versioning Standard §7.
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            perf
+            docs
+            chore
+            refactor
+            test
+            ci
+            build
+            style
+            revert
+            deps
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            PR title subject must start with a lowercase letter.
+            Example: `feat: add /wells/{id}/assets endpoint`

.github/workflows/release-please.yml

@@ -0,0 +1,21 @@
+name: release-please
+
+on:
+  push:
+    branches:
+      - production
+      - 'hotfix/v*'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+          target-branch: ${{ github.ref_name }}

.github/workflows/tests.yml

@@ -49,7 +49,7 @@ jobs:
 
     steps:
       - name: Check out source repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
 
       - name: Wait for database readiness
         run: |
@@ -141,7 +141,7 @@ jobs:
 
     steps:
       - name: Check out source repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
 
       - name: Wait for database readiness
         run: |

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}

api/search.py

@@ -67,7 +67,7 @@ def _get_contact_results(session: Session, q: str, limit: int) -> list[dict]:
     contacts = session.scalars(query).all()
     results = [
         {
-            "label": c.name,
+            "label": c.name or c.organization,
             "group": "Contacts",
             "properties": {
                 "email": [e.email for e in c.emails],

core/app.py

@@ -114,7 +114,7 @@ def full_openapi():
     def public_openapi():
         schema = get_openapi(
             title="Ocotillo API (Public)",
-            version="0.0.1",
+            version=settings.version,
             description="Public API schema (anonymous users)",
             routes=app.routes,
         )
@@ -218,6 +218,11 @@ async def swagger_ui_redirect():
     async def warmup():
         return {"status": "ok"}
 
+    @app.get("/health", tags=["meta"])
+    @public_route
+    async def health():
+        return {"status": "ok", "version": settings.version}
+
     return app