Skip to content

Migrate quickstart from Functions Core Tools v4 to Functions CLI v5 (func5)#20

Open
paulyuk wants to merge 6 commits into
Azure-Samples:mainfrom
paulyuk:paulyuk/funcs-cli-v5-migration
Open

Migrate quickstart from Functions Core Tools v4 to Functions CLI v5 (func5)#20
paulyuk wants to merge 6 commits into
Azure-Samples:mainfrom
paulyuk:paulyuk/funcs-cli-v5-migration

Conversation

@paulyuk

@paulyuk paulyuk commented Jun 17, 2026

Copy link
Copy Markdown
Member

What

Move the documented local-dev path from Azure Functions Core Tools v4 to the new Azure Functions CLI v5 preview, installed alongside any existing v4 as func5. This shrinks the local-dev story from three terminals to two and removes the separate Azurite install/start.

Why

The current README:

  • Tells users to brew install azure-functions-core-tools@4 + npm install -g azurite + run Azurite in its own terminal.
  • Calls v5 out as 'not yet compatible' (the early v5 previews couldn't load the Preview extension bundle, #5309).

That bundle issue is fixed in bundles@4.42.0-preview.2 (shipped via func5 setup --features python), and v5 auto-manages Azurite (func run / func start starts and stops it for you unless you pass --no-azurite). So the v4 + separate Azurite recipe is now strictly more work for new users.

What changed

File Change
README.md Prerequisites: drop the 'v4 only, v5 not compatible' line. Quickstart step 1: replace the brew + npm install with the official v5 install pattern (download v5 preview tar.gz/zip, alias as func5, run func5 setup --features python once). Quickstart step 3: collapse 3 terminals to 2 (Azurite goes away).
docs/troubleshooting.md Remove 'Stay on v4' and the Azurite 'connection refused' / 'InvalidHeaderValue' entries (v5 handles Azurite). Add a self-fix entry that points at the extension bundles workload. New 'Still using v4' section documents the fallback path for users who can't / don't want to add v5 yet.
chat.py, function_app.py, infra/scripts/*.sh, infra/scripts/*.ps1, docs/configuration.md All user-visible uv run func start references become uv run func5 start. Hydrate scripts hint at v5 auto-Azurite.

Test recipe

On a clean machine:

# Quickstart step 1 (Apple Silicon shown; -osx-x64-, -linux-x64-, or -win-x64- elsewhere)
mkdir -p ~/.azure-functions/v5 && cd ~/.azure-functions/v5
curl -LO https://github.com/Azure/azure-functions-core-tools/releases/download/v5.0.0-preview.2/func-osx-arm64.tar.gz
tar -xzf func-osx-arm64.tar.gz
mkdir -p ~/.local/bin && ln -sf ~/.azure-functions/v5/func ~/.local/bin/func5
# fresh shell so PATH picks up ~/.local/bin
func5 --version            # -> 5.0.0-preview.2+...
func5 setup --features python

# Quickstart steps 2–3
azd provision
./infra/scripts/hydrate-local-settings.sh
uv run func5 start         # one terminal, Azurite started for you
uv run python chat.py      # other terminal

Notes for reviewers / followups

  • This is off main, separate from README & usability fit and finish #17 (README usability) and infra: bump default modelCapacity 50 → 150 (avoid day-one 429s) #18 (capacity bump). Both add lines this PR rewrites; whichever lands second will need a tiny rebase.
  • Once v5 reaches GA, the 'Still using v4' section should be removed and the install step replaced with a brew formula / aka.ms one-liner.
  • I left the v5 download URLs pinned at v5.0.0-preview.2. We can swap to a 'latest preview' URL once Microsoft publishes one (currently the GitHub Releases page is the source of truth).
  • The func5 alias is intentional: it keeps the v4 func users have today out of the way. The official v5 binary IS func; the alias is just for coexistence.

paulyuk and others added 2 commits June 16, 2026 17:22
…func5)

Adopt the new Azure Functions CLI v5 preview, installed alongside any
existing v4 as 'func5'. This shrinks the local-dev story from three
terminals to two and removes the separate Azurite install/start.

What changed
- README Prerequisites: drop 'Core Tools v4 >= 4.12.0 (v5 preview not
  yet compatible)'. Recommend Functions CLI v5 installed as 'func5',
  with a one-line nod to v4 users (full fallback in troubleshooting).
- README Quickstart step 1: replace 'brew install
  azure-functions-core-tools@4 + npm install -g azurite' with the
  download-from-releases install pattern and a 'func5 setup --features
  python' one-shot that pulls host + python-worker + python-templates
  + the extension-bundles workload (the fix for #5309 on early v5
  previews).
- README Quickstart step 3: collapse three terminals to two. v5
  auto-starts Azurite, so the dedicated 'azurite ...' terminal goes
  away.
- docs/troubleshooting.md: invert the v5 advice. Remove the 'Stay on
  v4' note. Replace it with a self-fix entry that points at the
  extension bundles workload. Drop the dead Azurite 'Connection
  refused 127.0.0.1:10000' and 'InvalidHeaderValue' entries (v5
  manages Azurite for you). Add a new 'Still using v4' section that
  documents how to keep the v4 path working until v5 reaches GA.
- chat.py, function_app.py, docs/configuration.md, infra/scripts:
  every user-visible 'uv run func start' becomes 'uv run func5
  start', and the hydrate scripts now hint at the v5 auto-Azurite
  behavior.

Why
The repo currently tells users to install Core Tools v4 + Azurite +
the host runtime, and routes around an extension-bundle bug in early
v5 previews. v5-preview.2 ships the extension bundles workload (4.42
+) and resolves that bug; staying on v4 also means the user has to
maintain a separate Azurite install and run it in its own terminal.
Installing v5 as 'func5' avoids breaking any consumer that still
needs v4 'func'.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The earlier URL (Azure.Functions.Cli-osx-arm64-5.0.0-preview.2.tar.gz)
404s. The actual asset names on the v5 preview releases are
func-{osx|linux|win}-{x64|arm64}.{tar.gz|zip}. Verified all six exist.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@paulyuk paulyuk force-pushed the paulyuk/funcs-cli-v5-migration branch from 31328dc to 1f6e10d Compare June 17, 2026 00:22
paulyuk and others added 4 commits June 16, 2026 17:41
… workload callout

Drops OS-specific brew/curl/PowerShell snippets and the FUNC5_DIR archive recipe
in favor of links to the official install docs for uv, azd, func5, and the
connector-namespace CLI extension. The only inline command kept is
`func5 setup --features python` since the extension bundles workload is the
one template-specific, non-default thing.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…tures python by default

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…cally); add Azurite to prereqs; link uv (not Python) in prereq bullet

- func5 run replaces 'uv run func5 start' everywhere - v5 detects pyproject.toml and uses the uv-managed venv without the explicit 'uv run' prefix.
- Azurite added as an explicit prereq with install link; func5 launches it on demand but does not bundle it.
- Prereq bullet now links to uv (the thing you install) instead of Python 3.13 (the thing uv installs).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add TEAMS_MENTION_USER_ID and TEAMS_MENTION_NAME to the README go-live
block with inlined �z ad signed-in-user show subshells so users don't
have to copy ids manually. Mirror the same snippet in docs/configuration.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant