Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

WS6: Finalize the public API before GA

Aperta
  • Qualcosa non va?
#7,258 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@j7nw4r ci sta già lavorando.

Dal 28/7/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

Event Hubs

Summary

The public API must be settled before 1.0.0, because only backwards compatible growth is permitted after GA. The Azure SDK architecture board review is not complete, no archived API surface artifact exists, the error model carries a raw AMQP condition string with no reason enum, several transport options that .NET exposes are absent, and vcpkg.json declares a wrong version and an unused dependency.

Severity tags follow the key in #7252.

Motivation

The Azure SDK release checklist requires an architecture board API review and an archived API surface artifact. .NET keeps that artifact as sdk/eventhub/Azure.Messaging.EventHubs/api/Azure.Messaging.EventHubs.netstandard2.0.cs. The C++ package has no equivalent.

EventHubsException carries a raw condition string, a description, an IsTransient flag, and an optional status code (inc/azure/messaging/eventhubs/eventhubs_exception.hpp:38-65). .NET maps errors onto a FailureReason enum with eleven values (sdk/eventhub/Azure.Messaging.EventHubs/src/EventHubsException.cs:221-255), which gives a caller something to act on without parsing a string.

The C++ versioning guidelines state "DO be 100% backwards compatible with older versions of the same package" [cpp-versioning-backwards-compatibility] and "DO introduce a new package (with new assembly names, new namespace names, and new type names) if you must do an API breaking change" [cpp-versioning-new-package]. The C++ guidelines record no ABI or binary compatibility promise, so the constraint is source compatibility.

A sweep of the C++ options structs did not find a per-attempt timeout, a retry mode, WebSocket transport, a proxy, or a custom endpoint, all of which .NET exposes through EventHubsRetryOptions and EventHubConnectionOptions. That sweep was not exhaustive, so each item needs a decision rather than an assumption.

vcpkg.json declares version-string: 1.0.0 while the package is at a beta version, and it declares an opentelemetry-cpp dependency with the otlp-http feature that the library sources do not use (vcpkg.json:3-11). Note that #7259 may make that dependency real.

Proposal

  • Complete the Azure SDK architecture board API review for azure-messaging-eventhubs and azure-messaging-eventhubs-checkpointstore-blob. Produce and archive the API surface listing, the C++ analog of the .NET api/*.cs files. [GA blocker]
  • Decide whether the reason enum supplements the condition string or replaces it. A replacement is a breaking change and must land before 1.0.0. [GA blocker to decide]
  • Add a reason enum mapped from AMQP conditions, modeled on EventHubsException.cs:221-255, as a new member alongside the existing fields (inc/azure/messaging/eventhubs/eventhubs_exception.hpp:38-65). [GA quality bar]
  • Sweep ConsumerClientOptions and ProducerClientOptions against the .NET EventHubsRetryOptions and EventHubConnectionOptions. Decide each missing option as add-before-GA, add-after-GA, or never. [GA quality bar]
  • Correct vcpkg.json: fix version-string, and remove or justify the unused opentelemetry-cpp dependency (vcpkg.json:3-11). [GA quality bar]

Resolution of the earlier open question

This issue previously tagged the reason enum GA quality bar on the unverified assumption that the C++ SDK permits additive API growth after 1.0.0. The guidelines were then read directly, and they permit it: cpp-versioning-backwards-compatibility constrains source compatibility, and adding a new enum type plus a new accessor to EventHubsException keeps every existing caller compiling.

The tag therefore stays GA quality bar, but it holds only for a supplement. Removing or repurposing the existing condition string breaks callers and must land before 1.0.0. That is why the supplement-or-replace decision is split out above as its own blocker.

One caveat: the guidelines record no ABI promise, so adding a member to the exception class is safe for source builds but changes the class layout. Consumers who link a prebuilt binary must rebuild. Record that expectation with the decision.

Validation

  • The architecture board sign-off is recorded and the API surface artifact is archived in the repository.
  • The supplement-or-replace decision is recorded in this issue.
  • Every option in the sweep carries a recorded decision.
  • vcpkg.json declares the correct version and no unused dependency.
Lingua principale
C++
Stelle
206
Fork
173
Merge medio
2g 4h
PR unite (30g)
27

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Azure/azure-sdk-for-cpp

Tutte le issue di Azure/azure-sdk-for-cpp

Issue simili

Altre issue su C++

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.