diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fa03e8c..027c79c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,10 +11,10 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 20 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Setup .NET 10 - uses: actions/setup-dotnet@v4 + uses: actions/setup-dotnet@v5 with: dotnet-version: 10.0.x @@ -29,7 +29,7 @@ jobs: - name: Upload test results if: always() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v7 with: name: test-results path: '**/test-results.trx' @@ -39,10 +39,10 @@ jobs: needs: build-test if: github.ref == 'refs/heads/main' steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Setup .NET 10 - uses: actions/setup-dotnet@v4 + uses: actions/setup-dotnet@v5 with: dotnet-version: 10.0.x @@ -50,7 +50,7 @@ jobs: run: dotnet pack FireflyFramework.sln --configuration Release --output ./artifacts - name: Upload nupkgs - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v7 with: name: nupkgs path: ./artifacts/*.nupkg diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 602f24f..a2df1b9 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -40,10 +40,10 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 30 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Setup .NET 10 - uses: actions/setup-dotnet@v4 + uses: actions/setup-dotnet@v5 with: dotnet-version: 10.0.x @@ -75,7 +75,7 @@ jobs: - name: Upload test results if: always() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v7 with: name: test-results-${{ steps.version.outputs.version }} path: '**/test-results.trx' @@ -94,7 +94,7 @@ jobs: run: ls -lh ./packages - name: Upload nupkg + snupkg artifacts - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v7 with: name: nupkgs-${{ steps.version.outputs.version }} path: | @@ -126,7 +126,7 @@ jobs: - name: Attach packages to GitHub Release if: ${{ github.event_name == 'release' }} - uses: softprops/action-gh-release@v2 + uses: softprops/action-gh-release@v3 with: files: | ./packages/*.nupkg diff --git a/README.md b/README.md index 98eaa1f..6f16f43 100644 --- a/README.md +++ b/README.md @@ -252,25 +252,35 @@ rm WeatherForecast.cs # the template noise we don't need ### 2. Install the framework -The Firefly packages live on NuGet under the `FireflyFramework.*` -prefix. The starter meta-package wires the entire infrastructure tier -(Web, Cache, Observability, EDA, CQRS) in one call, so you only need -this single `add package` to start: +The Firefly packages live under the `FireflyFramework.*` prefix on +**two registries**, depending on the version you want: + +| Version channel | Registry | Setup | +|---|---|---| +| Stable releases (`26.04.01`) | NuGet.org | None — works out of the box | +| Pre-release builds (`26.05.01-preview`, `-rc`, …) | GitHub Packages | One-time `nuget.config` + a GitHub PAT with `read:packages` | + +The starter meta-package wires the entire infrastructure tier (Web, +Cache, Observability, EDA, CQRS) in one call, so you only need this +single `add package` to start: ```bash +# Stable release from NuGet.org dotnet add package FireflyFramework.Starter.Core + +# Or a pre-release from GitHub Packages (after one-time setup; see below) +dotnet add package FireflyFramework.Starter.Core --version 26.05.01-preview ``` +For the GitHub Packages path, follow the one-time setup in +[`docs/INSTALL.md`](docs/INSTALL.md) — it walks through PAT creation, +the `nuget.config` template, and the CI-friendly auth flow using the +auto-provided `GITHUB_TOKEN`. + If you want the rule engine, orchestration, or one of the IDP adapters, add the corresponding `FireflyFramework.` package on top (every `src//README.md` describes its own surface). -> **Note** — the published versions track the Java release line as a -> calendar version (currently `26.04.01`). The CI/release workflow -> (`.github/workflows/publish.yml`) pushes every `src/*` project to -> NuGet.org and GitHub Packages on each tagged release; see -> [`Releases & publishing`](#releases--publishing) below. - ### 3. Replace `Program.cs` ```csharp @@ -427,6 +437,7 @@ public surface, options class, and usage examples. | Document | Purpose | |---|---| +| [`docs/INSTALL.md`](docs/INSTALL.md) | How to install packages from NuGet.org, GitHub Packages, or local project references; one-time `nuget.config` + PAT setup | | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Tier-by-tier reference, dependency-direction graph, process model, versioning policy | | [`docs/SERVICE-SCAFFOLDING.md`](docs/SERVICE-SCAFFOLDING.md) | The canonical 5-project layout, naming conventions, dependency graph, bootstrap recipe | | [`docs/MIGRATION-GUIDE.md`](docs/MIGRATION-GUIDE.md) | Java → .NET cookbook covering Reactor, Spring DI, web layer, persistence, CQRS, EDA, resilience, observability | diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..1c602f0 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,216 @@ +# Installing Firefly Framework + +This guide covers every way to consume the Firefly Framework packages +from a .NET 10 project. Pick the path that matches where the version +you want to install is published. + +| Source | When to use | Setup effort | +|---|---|---| +| [**NuGet.org**](#nugetorg-public-stable-releases) | Stable, public releases (no `-preview` / `-rc` suffix) | None — `dotnet add` works out of the box | +| [**GitHub Packages**](#github-packages-pre-release--preview-builds) | Pre-release / preview / RC builds, internal mirror | One-time `nuget.config` + GitHub PAT | +| [**Local project references**](#local-project-references-contributors) | Developing against the framework itself | None — clone and reference projects directly | + +--- + +## Prerequisites + +* **.NET 10 SDK** — `dotnet --version` must report a `10.0.*` build. +* A target project — for a brand-new one, see the [README quickstart](../README.md#build-your-first-firefly-service). + +--- + +## NuGet.org (public stable releases) + +Stable releases are pushed to NuGet.org at the repository's calendar +version (e.g. `26.04.01`). No setup is needed: NuGet.org is the +default source on every fresh .NET install. + +```bash +dotnet add package FireflyFramework.Starter.Core +``` + +Browse the catalogue at . + +--- + +## GitHub Packages (pre-release & preview builds) + +Pre-release versions (anything with a `-preview`, `-rc`, or similar +suffix) and internal mirror copies of stable versions are published to +GitHub Packages at . + +GitHub Packages requires an authenticated source even for **public** +packages. The credential is a [GitHub Personal Access Token (PAT)](https://github.com/settings/tokens) +with the **`read:packages`** scope. + +### One-time setup + +#### 1. Create the PAT + +1. Open . +2. Set a meaningful name (e.g. *firefly-nuget-read*) and an expiry that suits your team policy. +3. Select **`read:packages`** (and only that — least-privilege keeps the token safe to commit to a CI secret store). +4. Click **Generate token** and copy the value somewhere safe. + +#### 2. Tell NuGet about the source + +Pick one of the two equivalent paths. + +**Option A — `dotnet nuget add source`** (one-time, machine-global): + +```bash +dotnet nuget add source https://nuget.pkg.github.com/fireflyframework/index.json \ + --name firefly-github \ + --username YOUR_GITHUB_USERNAME \ + --password YOUR_PAT \ + --store-password-in-clear-text +``` + +The `--store-password-in-clear-text` flag is required on macOS / Linux because the Windows credential manager isn't available there. + +**Option B — Project-local `nuget.config`** (commit-friendly, per-repo): + +Create a `nuget.config` next to your `.sln` file: + +```xml + + + + + + + + + + + + + + +``` + +`%VAR%` is expanded by NuGet from environment variables. Set them in +your shell profile or `.envrc`: + +```bash +export GITHUB_USERNAME=your-github-username +export GITHUB_PACKAGES_PAT=ghp_xxxxxxxxxxxx +``` + +That way the `nuget.config` is safe to commit — the credentials live in +the environment, not the repository. + +#### 3. Install a pre-release package + +```bash +dotnet add package FireflyFramework.Starter.Core --version 26.05.01-preview +``` + +The `--version` flag is required for pre-release versions (NuGet won't +pick a `-preview` build automatically). Use `--prerelease` to take the +latest pre-release build instead: + +```bash +dotnet add package FireflyFramework.Starter.Core --prerelease +``` + +### Using GitHub Packages from CI + +In a GitHub Actions workflow inside the **same organisation**, the +auto-provided `GITHUB_TOKEN` is enough — no PAT required: + +```yaml +- name: Authenticate to GitHub Packages + run: | + dotnet nuget add source https://nuget.pkg.github.com/fireflyframework/index.json \ + --name firefly-github \ + --username ${{ github.actor }} \ + --password ${{ secrets.GITHUB_TOKEN }} \ + --store-password-in-clear-text + +- name: Restore + run: dotnet restore +``` + +For workflows in **other** organisations, store a PAT with `read:packages` +in a repository secret (e.g. `FIREFLY_NUGET_PAT`) and reference it the +same way. + +--- + +## Local project references (contributors) + +If you're working *on* the framework itself, or you want to test an +unreleased change before it ships, reference the projects directly +instead of installing packages. + +```bash +git clone https://github.com/fireflyframework/fireflyframework-dotnet.git +cd fireflyframework-dotnet +dotnet build FireflyFramework.sln +``` + +Then in your consumer project: + +```bash +dotnet add reference \ + ../path/to/fireflyframework-dotnet/src/FireflyFramework.Starter.Core/FireflyFramework.Starter.Core.csproj +``` + +Or, in the `.csproj` directly: + +```xml + +``` + +This bypasses NuGet entirely; rebuilds in the framework checkout flow +into the consumer at the next `dotnet build`. + +--- + +## Listing every available version + +Once a source is configured, you can introspect what's published: + +```bash +# All Firefly packages (truncated by default; pass --take 100 to expand) +dotnet package search FireflyFramework --source firefly-github + +# Every version of one package +dotnet package search FireflyFramework.Starter.Core --source firefly-github --exact-match +``` + +Or open the GitHub Packages UI: every package has a *Versions* tab +listing each published build. + +--- + +## Troubleshooting + +**`Unable to load the service index for source https://nuget.pkg.github.com/...`** +The PAT is missing or expired. Verify with `dotnet nuget list source` +that the source is configured, then re-issue the PAT with `read:packages`. + +**`401 Unauthorized` on `dotnet restore`** +The credentials in `nuget.config` (or environment) don't match a token +with `read:packages`. The `Username` field is the GitHub username; the +`ClearTextPassword` is the PAT. + +**`The package 'FireflyFramework.X' is not found`** +The version you asked for isn't on the source you queried. Check the +GitHub Packages UI for the actual published versions. Pre-release builds +always need either `--version ` or `--prerelease` on the install. + +**`Package downgrade detected`** +Project transitive dependencies pinned a higher version than the one +you're installing. Either bump your direct install, or pin the +transitive in `Directory.Packages.props`. + +--- + +## See also + +* [`README.md`](../README.md) — five-minute pitch and the from-scratch quickstart. +* [`docs/CONFIGURATION.md`](CONFIGURATION.md) — every `Firefly:*` config section once a package is installed. +* [`docs/SERVICE-SCAFFOLDING.md`](SERVICE-SCAFFOLDING.md) — promoting a hello-world to the canonical 5-project layout. diff --git a/docs/README.md b/docs/README.md index 5f3f314..f2284a5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ recommended starting point. | Document | Audience | What it covers | |---|---|---| +| [`INSTALL.md`](INSTALL.md) | Anyone consuming the packages | Installing from NuGet.org (stable) vs. GitHub Packages (pre-release) vs. local project references; one-time `nuget.config` template; PAT creation; CI authentication. | | [`ARCHITECTURE.md`](ARCHITECTURE.md) | Anyone integrating with the framework | The four-tier layering (Foundational → Platform → Adapters → Starters), inter-project dependency direction, the process model the runtime assumes, and the framework's versioning policy. | | [`MODULES.md`](MODULES.md) | Anyone picking which package(s) to install | One-line description of every `src/*` project paired with its Java original, organised by tier. The "what's in this package" reference. | | [`SERVICE-SCAFFOLDING.md`](SERVICE-SCAFFOLDING.md) | Service authors building on the framework | The canonical five-project layout (`.Interfaces` / `.Models` / `.Core` / `.Web` / `.Sdk`), naming conventions, dependency graph, and a step-by-step bootstrap recipe modelled on the Orders sample. | @@ -16,10 +17,11 @@ recommended starting point. If you're new to the framework, read in this order: -1. **[`ARCHITECTURE.md`](ARCHITECTURE.md)** — orient on the layering model and the dependency direction. Five minutes. -2. **[`SERVICE-SCAFFOLDING.md`](SERVICE-SCAFFOLDING.md)** — see what a real service looks like end-to-end before reading individual module docs. Ten minutes. -3. **[`MODULES.md`](MODULES.md)** — skim the catalogue; bookmark the modules you'll use. -4. **[`CONFIGURATION.md`](CONFIGURATION.md)** — keep open while wiring up your `appsettings.json`. +1. **[`INSTALL.md`](INSTALL.md)** — get the packages resolving in your project. Two minutes. +2. **[`ARCHITECTURE.md`](ARCHITECTURE.md)** — orient on the layering model and the dependency direction. Five minutes. +3. **[`SERVICE-SCAFFOLDING.md`](SERVICE-SCAFFOLDING.md)** — see what a real service looks like end-to-end before reading individual module docs. Ten minutes. +4. **[`MODULES.md`](MODULES.md)** — skim the catalogue; bookmark the modules you'll use. +5. **[`CONFIGURATION.md`](CONFIGURATION.md)** — keep open while wiring up your `appsettings.json`. If you're porting an existing Java service, start with [`MIGRATION-GUIDE.md`](MIGRATION-GUIDE.md) instead.