readme

Author: y3rsh

README.md

@@ -1,6 +1,34 @@
 # robot-stack
 
-Tools to inspect, tag, and build Opentrons robots across the multi-repo software stack.
+Python tooling to plan Opentrons robot releases across the multi-repo stack (Flex and OT-2): which repos need tags, what each tag should look like, where CI runs after you push, and which CloudFront invalidation to run when builds finish.
+
+## Recommended workflow (Cursor)
+
+Open this repo in [Cursor](https://cursor.com) and start a chat along these lines:
+
+> I need to do a new release for **Flex** (or **OT-2**). It will be **internal** or **external**, and **stable**, **alpha**, or **beta** (Flex internal/external use **stable** or **unstable** for alpha).
+
+Workspace rules in `.cursor/rules/` teach the agent how to run the scripts below. It will sync local clones, print release analysis, and suggest copy-paste `git tag` / `git push` commands. **Nothing is pushed or invalidated automatically**; review the output, confirm you agree, then run the printed steps yourself.
+
+Prompt Cursor as above and it will walk you through the full release in order, running the advisory scripts and printing what to do next at each stage:
+
+1. **Plan tags** — runs `just go` to show what needs tags and the tag shape per repo.
+2. **Push tags** — prints `git tag` / `git push` commands for you to run (stack repos first, app last).
+3. **Track builds** — runs `just track-builds` after the app tag is pushed to surface app, kickoff, and robot OS workflow runs.
+4. **Verify builds** — reminds you to wait for CI and spot-check manifests if needed.
+5. **Invalidate CDN** — runs `just invalidate-cloudfront` to print the exact `aws cloudfront create-invalidation` command (distribution and paths) for your tag and channel.
+
+### TODO: release checklists
+
+Generate a **release checklist** for each run (tag plan, commands run, build links, invalidation, sign-off). Checklists will be committed in this repository and published on [GitHub Pages](https://opentrons.github.io/robot-stack/) alongside asset inventories and release guides, with an index page listing past releases.
+
+The sections below document the same commands for interactive or scripted use without Cursor.
+
+**Live asset inventories and release guides:** [opentrons.github.io/robot-stack](https://opentrons.github.io/robot-stack/)
+
+**Regenerate that site:** run the [Publish asset inventory to GitHub Pages](https://github.com/Opentrons/robot-stack/actions/workflows/asset-inventory-pages.yml) workflow (`workflow_dispatch` on `main`, or push to `main`).
+
+## Setup
 
 The only external dependency is [uv](https://docs.astral.sh/uv/).
 

automation/ot2_tag_allocation.py

@@ -52,11 +52,7 @@ def _external_stability_bases_in_month(
             year, month, release_num, tag_pre, tag_pre_num = decode_ot2_external_version(version)
         except ValueError:
             continue
-        if (
-            (year, month) == (release_date.year, release_date.month)
-            and tag_pre == stability
-            and tag_pre_num is not None
-        ):
+        if (year, month) == (release_date.year, release_date.month) and tag_pre == stability and tag_pre_num is not None:
             bases.add(release_num)
     return bases
 

automation/release_guides.py

@@ -6,7 +6,7 @@
 from pathlib import Path
 from typing import Final, Tuple
 
-from automation.asset_urls import APP_CHANNEL_YAMLS, app_manifest_url, app_yaml_url, robot_manifest_url
+from automation.asset_urls import APP_CHANNEL_YAMLS, app_manifest_url, robot_manifest_url
 from automation.flex_urls import FLEX_EXTERNAL, FLEX_INTERNAL, FLEX_ROBOT_PREFIX
 from automation.ot2_urls import OT2_EXTERNAL, OT2_INTERNAL, OT2_ROBOT_PREFIX
 from automation.site_nav import GUIDE_NAV, render_site_header, robot_name_html, site_nav_css

automation/site_nav.py

@@ -205,20 +205,13 @@ def _render_nav_link(item: SiteLink, current_page: str) -> str:
     is_current = nav_link_is_current(item, current_page)
     current_attr = ' aria-current="page"' if is_current else ""
     current_class = ' class="nav-current"' if is_current else ""
-    return (
-        f'<a href="{html.escape(item.filename)}"{current_class}{current_attr}>'
-        f"{html.escape(item.title)}</a>"
-    )
+    return f'<a href="{html.escape(item.filename)}"{current_class}{current_attr}>{html.escape(item.title)}</a>'
 
 
 def _render_nav_block(kind: str, links: Tuple[SiteLink, ...], current_page: str) -> str:
     """Render a vertical block of links under a section label."""
     link_html = "".join(_render_nav_link(item, current_page) for item in links)
-    return (
-        f'<div class="nav-block">'
-        f'<span class="nav-kind">{html.escape(kind)}</span>{link_html}'
-        f"</div>"
-    )
+    return f'<div class="nav-block"><span class="nav-kind">{html.escape(kind)}</span>{link_html}</div>'
 
 
 def render_site_header(current_page: str) -> str:
@@ -227,9 +220,9 @@ def render_site_header(current_page: str) -> str:
     for group in PRODUCT_NAV:
         groups.append(
             f'<div class="nav-group">'
-            f'{robot_name_html(group.label)}'
-            f'{_render_nav_block("Assets", group.asset_links, current_page)}'
-            f'{_render_nav_block("Guides", group.guide_links, current_page)}'
+            f"{robot_name_html(group.label)}"
+            f"{_render_nav_block('Assets', group.asset_links, current_page)}"
+            f"{_render_nav_block('Guides', group.guide_links, current_page)}"
             f"</div>"
         )
 

justfile

@@ -8,21 +8,24 @@
 
 # update opentrons repositories
 @go *args:
-    uv run ./automation/go.py {{args}}
+    uv run ./automation/go.py {{ args }}
 
 # find GitHub Actions build jobs for a pushed OT-2 or Flex release tag
 @track-builds *args:
-    uv run ./automation/track_builds.py {{args}}
+    uv run ./automation/track_builds.py {{ args }}
 
 # print CloudFront invalidation command for a release tag
 @invalidate-cloudfront *args:
-    uv run ./automation/invalidate_cloudfront.py {{args}}
+    uv run ./automation/invalidate_cloudfront.py {{ args }}
 
 # format and lint with ruff
 @fix:
     uv run ruff format .
     uv run ruff check --fix --unsafe-fixes .
 
+# format justfile, lint/format Python, and type-check (run before commit or PR)
+@prep: fmt fix ty
+
 @manifest:
     uv run ./automation/manifest.py