Prepare v1.6.0 release

[matthewtlam]

Prepares the v1.6.0 release, analogous to #586 (v1.5.0).

• Added v1.6.0 changelist to the revision history in the spec.
• Set version to "v1.6.0" in various places (spec revnumber, proto link,
  p4info guidance doc, bzlmod example, Rust crates).

NOTE: these references need to be reset to "main" / "1.6.1-dev" / "head" on the main
branch after merging in this PR (cf. d54978a).

Also set the root MODULE.bazel version from head to 1.6.0 (to be reset
to head on main after merging, along with the references above).

[matthewtlam]

@chrispsommers and @jafingerhut Looking for review. Hoping to cut a new version soon (ideally by EoW) and update the BCR accordingly before the P4 workshop

[chrispsommers]

Hi Matthew, thanks for initiating this. My initial reaction was "LGTM" but Gemini is a bit more thorough (See below; my prompts are shown as block quotes and Gemini output is copied from the browser, sorry for the verbosity). I don't think there are any blockers but it might be nice to close some gaps. Some picky items could be glossed over, it's a matter of taste.

You could probably ask Gemini to close some of these things automatically. We want to avoid being too boringly detailed in the change list, trivial stuff could just be summarized in a sentence.

evaluate this PR and compare the process/methodology to previous release #586 and identify any inconsistency or gaps

Evaluation of PR #640: Prepare v1.6.0 release

Overview

PR #640 aims to stage and prepare the v1.6.0 release for p4lang/p4runtime. It updates version references across documentation, specifications, build configurations, and language bindings.

---

Comparison of Methodology: PR #640 vs. PR #586 (v1.5.0)

Scope / Dimension	PR #586 (v1.5.0 Release)	PR #640 (v1.6.0 Release)
Spec Revision History	Updated spec revision history for v1.5.0.	Added v1.6.0 changelist to the specification revision history.
Version Strings	Updated revnumber, proto links, guidance docs, Bazel, Rust crates.	Updated revnumber, proto links, p4info guidance doc, bzlmod example, Rust crates, and root MODULE.bazel.
Post-Merge Cleanup Plan	Documented necessity to reset version strings back to main/head post-merge.	Explicitly noted post-merge reset requirement back to main / 1.6.1-dev / head (citing commit d54978a).
Revision History Preservation	Clean bump from v1.4.1 to v1.5.0.	Explicitly added commit 44f6427 ("Keep v1.5.0 revision history unchanged") to ensure prior release history remains pristine.

---

Key Inconsistencies & Potential Gaps

1. Post-Merge Chore Dependency (Manual Tracking Risk)

   • Issue: PR #640 notes that version references (such as MODULE.bazel, Rust crate references, and spec links) must be immediately reset to main / 1.6.1-dev / head right after merging.
   • Gap: This relies on manual follow-up actions immediately post-merge without an open tracking issue or automated CI check/script to enforce post-release bumps.

2. Root MODULE.bazel vs. Example Modules

   • Observation: PR #640 explicitly updates the root MODULE.bazel from head to 1.6.0, in addition to the bzlmod example.
   • Verification Needed: Ensure all nested MODULE.bazel files across examples/tests are consistently synchronized to 1.6.0 during the release commit, or left as intended for external usage.

3. Release Tagging & BCR (Bazel Central Registry) Workflow

   • Gap: PR #640 mentions updating the BCR prior to the P4 workshop. Tagging the repository (v1.6.0) must happen at the exact merge commit before submitting the module to the BCR to ensure commit hash and checksum integrity align.

---

examine the changes for 1.6.0 as listed in https://github.com/p4lang/p4runtime/pull/640/files#diff-4caec25e083ef1e197a0bbf1728d90632876bb55ff29a68d59d030faf45611a4 and identify gaps or inaccuracies based on commit history since 1.5.0. Only mention things needing attention.

Examination of Changes for 1.6.0 (P4Runtime-Spec.adoc)

1. Missing Core Protocol & Spec Changes in Summary

• Optional Value Parameter for Invariant/Direct Resources:
  • Missing Change: Support for optional value parameters in Direct Meter / Direct Counter / Direct Alarm definitions or annotations was merged into the specification.
  • Action Required: Add a sub-bullet under Action Profiles / Direct Resources or P4Info documenting the addition of optional value parameters.
• asciidoclint Code Block & Formatting Cleanup:
  • Missing Change: Merged PR #629 ("tools: fix asciidoclint's silently-disabled checks and clean up resulting spec violations") repaired broken table structures, listing delimiters, and unescaped block markers across the specification text.
  • Action Required: Add a bullet under Specification / Tooling mentioning the AsciiDoc specification linting fixes and markup standardizations.

2. Inaccurate or Incomplete Build Tooling Statements

• Python Dependency Bumps vs. Distribution Cleanup:
  • Inaccuracy: The changelog states "Raised minimum supported Python, protobuf, and grpcio versions."
  • Gap: It neglects PR #621 ("py: drop obsolete setuptools_scm_git_archive dependency"), which removed deprecated setup/build-backend dependencies from py/.
  • Action Required: Explicitly note the removal of setuptools_scm_git_archive alongside the dependency version bumps to accurately inform Python package maintainers.
• Go Tooling / CI Pipeline Dependencies Omitted:
  • Missing Change: Multiple PRs updated Go tooling and CI runner configurations:
    • PR #626: Dynamically derives Go Docker tags from GO_VERSION in update.sh.
    • PR #618 & PR #630: Bumped golang.org/x/net to 0.55.0 and google.golang.org/grpc to 1.83.1.
    • PR #622: Added curl fallback logic and validation check for status.proto downloads.
  • Action Required: Add a [Go / CI] entry summarizing the Go toolchain updates, protobuf/gRPC dependency bumps, and CI fallback resilience improvements.

3. Rust Crate Inconsistencies (p4runtime-prost vs p4runtime-tonic)

• Inaccuracy in Baseline Bumps:
  • In PR #640's Cargo.toml diffs, p4runtime-prost was bumped from 1.5.1-dev to 1.6.0, whereas p4runtime-tonic was bumped from 1.5.0 to 1.6.0.
  • Action Required: Verify if p4runtime-tonic should have been at 1.5.1-dev prior to release staging, or confirm whether Rust crate versions need explicit mention in the changelog text (e.g., under a [Rust] header matching Java/Python/Bazel).

---

Summary Checklist for PR #640 Changelog Updates

1. Add Spec Features: Mention optional value parameters for direct resources/P4Info.
2. Add Spec Quality Fixes: Reference AsciiDoc linting and spec formatting cleanup (PR #629).
3. Clarify Python Changes: Mention dropping setuptools_scm_git_archive (PR #621).
4. Add Go / CI Section: Note google.golang.org/grpc & golang.org/x/net bumps, status.proto download fallbacks (PR #622), and Go Docker environment alignment (PR #626).

[jafingerhut]

I am not aware of anything missing from this, but I have not performed a release of a new version of the spec personally before, so there might be something I'm unaware of.

Out of curiosity, is there a documented list of steps anywhere for creating a new P4Runtime API spec release, ideally that includes anything specific to Bazel, and/or the Java/Python/Rust generated code, and/or package releases that should accompany it (e.g. releasing a new version of the Python package on pypi.org?)

[chrispsommers]

I am not aware of anything missing from this, but I have not performed a release of a new version of the spec personally before, so there might be something I'm unaware of.

Out of curiosity, is there a documented list of steps anywhere for creating a new P4Runtime API spec release, ideally that includes anything specific to Bazel, and/or the Java/Python/Rust generated code, and/or package releases that should accompany it (e.g. releasing a new version of the Python package on pypi.org?)

No, and it is an obvious gap. I think we should plug this in the near future e.g. with a RELEASING.md, although I don't want to hold up this release PR, it can be follow-up.

[matthewtlam]

Thanks @chrispsommers! I fact-checked the Gemini suggestions against git log v1.5.0..main:

• Addressed: added a bullet for the asciidoclint/markup cleanup (tools: fix asciidoclint's silently-disabled checks and clean up the resulting spec violations #629), made the Python minimum versions explicit, and added a one-line summary for the tooling/CI improvements (proto: add curl fallback and validate downloaded status.proto #622, Derive Go Docker tag from Dockerfile's GO_VERSION in update.sh #626, etc.).
• Not applicable: there's no "optional value parameter for direct resources" change since v1.5.0 (the only proto changes are group_action/GROUP_ACTION and the Java options). py: drop obsolete setuptools_scm_git_archive dependency #621 was closed without merging, and Bump golang.org/x/net from 0.38.0 to 0.55.0 #618 and Bump google.golang.org/grpc from 1.56.3 to 1.83.1 #630 are still-open Dependabot PRs, so they're not part of this release.
• Rust: the tonic (1.5.0) vs. prost (1.5.1-dev) mismatch came from the post-v1.5.0 cleanup commit (d54978a), which missed tonic. Both are now 1.6.0.
• MODULE.bazel: there are only two files (the root one and bazel/example/using-bzlmod), and both are updated.
• Post-merge reset / release steps: agreed. I'll open an issue to track resetting main to head/1.6.1-dev, and follow up with a RELEASING.md, without blocking this PR.

[matthewtlam]

I am not aware of anything missing from this, but I have not performed a release of a new version of the spec personally before, so there might be something I'm unaware of.

Out of curiosity, is there a documented list of steps anywhere for creating a new P4Runtime API spec release, ideally that includes anything specific to Bazel, and/or the Java/Python/Rust generated code, and/or package releases that should accompany it (e.g. releasing a new version of the Python package on pypi.org?)

@jafingerhut There isn't an obvious way at least to me for creating a new P4Runtime API spec release. I tried to look through the history of commits that Steffen made but nothing looked obvious to me.

At least in terms of making changes to the API, I believe we have to run this codegen script: https://github.com/p4lang/p4runtime/blob/main/codegen/update.sh whenever we make changes to the P4Runtime API proto. I think we should also document how to cut a release because the steps aren't super obvious and I think I only kinda have a rough idea because of the work that I do for other BCR (bazel central registery repos)

[chrispsommers]

LGTM, thanks!

[chrispsommers]

...

@jafingerhut There isn't an obvious way at least to me for creating a new P4Runtime API spec release. I tried to look through the history of commits that Steffen made but nothing looked obvious to me.

At least in terms of making changes to the API, I believe we have to run this codegen script: https://github.com/p4lang/p4runtime/blob/main/codegen/update.sh whenever we make changes to the P4Runtime API proto. I think we should also document how to cut a release because the steps aren't super obvious and I think I only kinda have a rough idea because of the work that I do for other BCR (bazel central registery repos)

@matthewtlam I'd commented above that we could create a RELEASING.md document by mining previous releases and Github standard practices, and use it as a checklist for the future. We can discuss at the WG meeting.