Skip to content

Consumer install guide + Node 24-ready GitHub Actions majors#21

Merged
ancongui merged 1 commit into
mainfrom
chore/install-guide-action-bumps
May 7, 2026
Merged

Consumer install guide + Node 24-ready GitHub Actions majors#21
ancongui merged 1 commit into
mainfrom
chore/install-guide-action-bumps

Conversation

@ancongui
Copy link
Copy Markdown
Contributor

@ancongui ancongui commented May 7, 2026

Summary

Two follow-ups from the first publish run.

`docs/INSTALL.md` — new

A self-contained guide for end users consuming the framework packages. Covers all three install paths the workflow produces:

Path When to use Setup
NuGet.org Stable releases None
GitHub Packages Pre-release / preview builds One-time `nuget.config` + `read:packages` PAT
Local project references Contributors developing against the framework None

Walks through PAT creation (minimal `read:packages` scope), the two `nuget.config` styles (`dotnet nuget add source` machine-global vs. project-local with `%ENV%` substitution), the CI-friendly path using the auto-provided `GITHUB_TOKEN` inside org-internal workflows, and `--version` vs. `--prerelease` semantics. Includes a Listing every available version section and a four-entry Troubleshooting section.

README + docs/README.md updates

  • The "Build your first Firefly service" install step in the README now distinguishes the two registries with a decision table and points at INSTALL.md for the GitHub Packages setup.
  • INSTALL.md is added to the Documentation table in the README and to docs/README.md as the new first step in the recommended reading order.

GitHub Actions — Node 24-ready majors

The first publish run produced this deprecation annotation:

Node.js 20 actions are deprecated … Actions will be forced to run with Node.js 24 by default starting June 2nd, 2026.

Bumped every action in both workflows to its current major:

Action Before After
`actions/checkout` `@v4` `@v6`
`actions/setup-dotnet` `@v4` `@v5`
`actions/upload-artifact` `@v4` `@v7`
`softprops/action-gh-release` `@v2` `@v3`

Major-tag floats — security patches land automatically inside the major.

Verification

  • `dotnet build FireflyFramework.sln` — 0 errors / 0 warnings
  • `dotnet test FireflyFramework.sln --no-build` — 346 / 346 passing

The next `workflow_dispatch` run will exercise the new action versions and produce a clean log without the Node 20 annotation.

…jors

Two follow-ups from the first publish run:

## docs/INSTALL.md — new

A self-contained guide for end users who want to consume the framework
packages. Covers all three install paths the workflow produces:

* **NuGet.org** — the canonical path for stable releases. No setup —
  works out of the box on a fresh `dotnet --version`.
* **GitHub Packages** — for pre-release builds (anything with a
  `-preview` / `-rc` suffix) and internal mirror copies of stable
  versions. Walks through:
    * PAT creation with the minimal `read:packages` scope.
    * `dotnet nuget add source` (machine-global) vs. project-local
      `nuget.config` (commit-friendly with `%ENV%` substitution).
    * The CI-friendly path using the auto-provided `GITHUB_TOKEN`
      inside org-internal workflows; falling back to a stored PAT
      for cross-org consumers.
    * `--version` vs. `--prerelease` semantics — pre-release versions
      are not picked up by the default install.
* **Local project references** — for contributors developing
  against an unreleased change. `git clone` + `dotnet add reference`
  bypasses NuGet entirely.

Plus a *Listing every available version* section with the
`dotnet package search` invocations and a four-entry
*Troubleshooting* section covering the most common errors
(401, missing service index, package-not-found, package-downgrade).

## README + docs/README.md updates

* The "Build your first Firefly service" install step in the
  top-level README now distinguishes the two registries with a
  decision table and points at INSTALL.md for the GitHub Packages
  setup.
* INSTALL.md is added to the Documentation table in the README and
  to docs/README.md as the new first-step in the recommended reading
  order ("get the packages resolving in your project. Two minutes.").

## GitHub Actions — Node 24-ready majors

The first publish run produced a deprecation annotation:
> "Node.js 20 actions are deprecated … Actions will be forced to run
>  with Node.js 24 by default starting June 2nd, 2026."

Bumped every action in both workflows to its current major (each of
which ships on Node 22 / 24, resolving the deprecation):

| Action | Before | After |
|---|---|---|
| `actions/checkout` | `@v4` | `@v6` |
| `actions/setup-dotnet` | `@v4` | `@v5` |
| `actions/upload-artifact` | `@v4` | `@v7` |
| `softprops/action-gh-release` | `@v2` | `@v3` |

Major-tag floats (no patch / minor pin) — the GitHub Actions guidance
is to track the major so security patches land automatically. The
publish workflow is otherwise unchanged.

Build: 0 errors / 0 warnings. Tests: 346 / 346 still passing.
@ancongui ancongui merged commit 2f5b9aa into main May 7, 2026
@ancongui ancongui deleted the chore/install-guide-action-bumps branch May 7, 2026 18:15
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