Skip to content

Add GETTING_STARTED_V1.6.md beta guide - #8703

Merged
Aaronontheweb merged 2 commits into
akkadotnet:devfrom
Aaronontheweb:docs/v1.6-getting-started
Oct 1, 2026
Merged

Aaronontheweb merged 2 commits into
akkadotnet:devfrom
Aaronontheweb:docs/v1.6-getting-started

Conversation

@Aaronontheweb

@Aaronontheweb Aaronontheweb commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

Purpose

The Akka.NET website is frozen on v1.5 docs until v1.6 stabilizes. Beta users
have no in-repo guide to work from. This PR adds one: GETTING_STARTED_V1.6.md
at the repo root, rendered directly on GitHub, plus a short pointer to it near
the top of README.md.

Merge order: merge this after #8701. #8701 refreshes
docs/articles/deployment/native-aot.md, which the Native AOT section here
links to for details - on dev today that page is stale relative to the AOT
work that already landed.

Sections

  1. What's in v1.6 - net10.0-only targeting, Akka.Hosting shipping from this
    repo (package ids, the version-alignment requirement, Microsoft.Extensions.*
    10.0.0 floor), Artery, the source-generated V2 serializer, and Native AOT
    support in progress. Links BREAKING_CHANGES_V1.6.md.
  2. Upgrading from 1.5 - third-party plugin compatibility and a pointer to
    the ledger's Wire rows before a rolling upgrade.
  3. Getting started with Akka.Hosting - the package references (including
    the Microsoft.Extensions.Hosting package Akka.Hosting itself doesn't
    carry) and a minimal Host.CreateApplicationBuilder + AddAkka sample.
  4. Native AOT and trimming - what CI verifies today (a local ActorSystem
    and an Akka.Hosting app, both PublishAot), what's only been manually
    probed (Remote over Artery - classic DotNetty does not work under AOT at
    all), what's unsupported for now (Cluster, Persistence, cluster tools), the
    Setup APIs that replace HOCON type names (and their one-setup-per-type
    gotcha), and the stream-refs/manifest-serializer exceptions. Links the
    fuller docs/articles/deployment/native-aot.md for details instead of
    repeating it.
  5. Source-generated serializer (Akka.Serialization.V2) - package reference,
    protocol interface, message type, serializer declaration, registration, and
    how it composes (or doesn't) with Akka.Hosting's AddSetup/WithCustomSerializer.
    Links docs/articles/serialization/source-generated-serialization.md for
    the full reference.
  6. Enabling Artery - the HOCON to turn it on, the experimental/production
    warning Akka.NET logs itself, the address-scheme/port change, and the one
    supported transport.
  7. Getting help / reporting beta issues - GitHub Issues/Discussions/Discord.

Verification

  • All three C# samples (Akka.Hosting minimal sample, the Setup-APIs sample used
    in the Native AOT section, and the Akka.Serialization.V2 sample) were built
    and run as standalone console apps referencing the real projects in this repo
    (Akka.csproj, Akka.Hosting.csproj, Akka.Serialization.V2.csproj +
    its generator wired in as an analyzer, the same way Akka.Remote.csproj
    does). Each one compiled and produced the expected output; the code in the
    doc is an exact subset of what ran - re-verified again after a round of
    review fixes by rebuilding from the final doc text verbatim.
  • The AOT csproj snippet was checked both ways: PublishAot=true alone (no
    RuntimeIdentifier condition) against a ProjectReference to Akka.csproj
    produces ~20 IL2026/IL2067/etc. trim warnings on dotnet publish; adding
    <RuntimeHostConfigurationOption Include="Akka.DynamicTypeLoading" Value="false" Trim="true" /> reduces that to zero and the published native
    binary runs correctly.
  • The version-float claim was checked directly: Version="*-beta*" resolves
    to Akka 1.5.71 on dotnet restore (confirmed via project.assets.json);
    Version="1.6.0-beta*" fails with NU1102 as intended.
  • builder.AddSetup(registration.CreateSetup()) from Akka.Hosting, composed
    with a source-generated Akka.Serialization.V2 serializer, was built and run
    end to end.
  • Every other claim (target frameworks, package ids, the AotCanary CI job,
    the Akka.DynamicTypeLoading switch, Artery's HOCON/transport support and
    its runtime warning/address scheme, the generator's diagnostics) was checked
    against the current dev source, not assumed.
  • markdownlint (same config as CI's .markdownlint.json) and cspell (CI's
    docs/cSpell.json) both run clean against the new file and the README
    change, and the full docs/**/*.md tree still passes after the dictionary
    addition. Note: CI's own lint/spellcheck jobs only glob docs/**/*.md, so
    these two root-level files aren't covered by CI - I ran both tools locally
    against them anyway and added netstandard to the shared dictionary.

Test plan

The Akka.NET website stays on v1.5 docs until v1.6 stabilizes, so beta
users need a guide that lives in the repo. Covers what changed in v1.6
(net10.0-only, Akka.Hosting now shipping from this repo, Artery, the
V2 source-generated serializer, and Native AOT support), with a
getting-started sample for Akka.Hosting, the Setup APIs that replace
HOCON type names under Native AOT, a working Akka.Serialization.V2
sample, and the HOCON to turn on Artery. Adds "netstandard" to the
cspell dictionary used by the new page.
…witch

An Opus review that actually restored and built the samples found several
problems: the *-beta* version wildcard silently resolves to the 1.5.71
release on NuGet instead of failing, so readers following the Hosting
sample would get v1.5 without knowing it; the Hosting sample needs an
explicit Microsoft.Extensions.Hosting package reference for
Host.CreateApplicationBuilder, which Akka.Hosting itself doesn't carry;
and the AOT csproj snippet copied the canary's RID-conditioned property
group, which silently skips AOT when a reader runs `dotnet publish`
without `-r`.

Switches every package reference to `1.6.0-beta*` (fails loudly with
NU1102 until a real beta ships, instead of quietly restoring 1.5),
reorders the Hosting sample so the package step comes first, simplifies
the AOT csproj snippet to just PublishAot=true plus a separate note
about the ProjectReference-only switch, and corrects several other
claims a closer read of the source turned up: classic DotNetty remoting
does not work at all under Native AOT (Artery is the target, confirmed
by one manual probe, not a CI canary); ActorSystemSetup keeps one setup
per type, so a second SerializationSetup replaces rather than merges;
Akka.Hosting's AddSetup composes with the V2 serializer but
WithCustomSerializer silently replaces it; Artery logs its own
"don't use in production" warning and changes the address scheme and
default port; and the field-index diagnostics are AKKASG005/AKKASG026,
not a blanket "missing index" rule. Adds an "Upgrading from 1.5" note
on third-party plugin compatibility and the ledger's Wire rows.

Re-verified by rebuilding all three C# samples (Hosting, the combined
Setup APIs, and the V2 serializer) from the doc text verbatim, plus a
standalone check that `*-beta*` resolves to Akka 1.5.71 while
`1.6.0-beta*` fails with NU1102, and that the simplified AOT csproj
snippet produces zero trim/AOT warnings with the manual switch and many
without it.
@Aaronontheweb
Aaronontheweb merged commit 05cb1fc into akkadotnet:dev Oct 1, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant