bigquery, bigquery-derive: hide macro implementation details behind #[doc(hidden)] pub mod __private before 1.0

Đang mở
  • Có gì không ổn?
#7,449 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
42/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
rust
Lĩnh vực
api, backend

Hướng nghiên cứu

Start with src/bigquery/src/query/from_sql.rs, src/bigquery/src/query.rs, and src/bigquery-derive/src/lib.rs, then read the linked contributor guide section on proc-macro crates. Trace the derive-generated calls and the runtime types they need before changing the public API. Done means generated code routes through the hidden module, the derive crate documents its supported imports, and both crates receive compatible breaking version bumps.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

api: bigquery type: cleanup
Summary

google-cloud-bigquery and google-cloud-bigquery-derive currently expose procedural-macro implementation details directly in google-cloud-bigquery's documented public API (google_cloud_bigquery::query) and emit calls directly to user-facing methods instead of routing generated code through a #[doc(hidden)] pub mod __private module.

Because google-cloud-bigquery was recently bumped to 1.0.0 on main (#7424, not yet released), shipping 1.0.0 as-is will freeze macro-internal types and trait methods under 1.x SemVer.

Problem Details

Per Rust proc-macro conventions (serde::__private, thiserror::__private, etc.), README.md ("any public symbol that is not part of the public API have the #[doc(hidden)] attribute set"), and doc/contributor/howto-guide-handwritten-client-api.md:

Generated code calls only a #[doc(hidden)] pub mod __private module in the runtime crate, never the user-facing API. Otherwise every method used by the generated code is frozen, and cargo-semver-checks cannot detect violations.

Currently:

  1. Derive-only types and methods are exposed in google_cloud_bigquery::query:
    • google_cloud_bigquery::query::SqlValue (src/bigquery/src/query/from_sql.rs, re-exported in src/bigquery/src/query.rs) is not returned or accepted by any user-facing Row or client API; it only exists to pass cell data into FromSql::from_value.
    • SqlValue::take explicitly documents that it is "Used by the #[derive(FromSql)] macro to extract struct fields", yet neither SqlValue nor SqlValue::take is marked #[doc(hidden)].
    • FromSql has a rustdoc warning ("Do not implement this trait directly. ... New methods (such as Arrow conversion methods) may be added in future versions, which would break manual implementations"), but FromSql is not sealed via a #[doc(hidden)] supertrait and FromSql::from_value(value: SqlValue) is not #[doc(hidden)]. Prose warnings do not exclude public traits or methods from SemVer or cargo-semver-checks.
  2. Generated code calls user-facing methods and unrooted paths directly (src/bigquery-derive/src/lib.rs):
    • #[derive(FromRow)] expands to row.take(...) on google_cloud_bigquery::query::Row and spells std::convert::TryFrom, std::result::Result, google_cloud_bigquery::query::Row, and google_cloud_bigquery::error::RowError without leading ::.
    • #[derive(FromSql)] expands to value.take(...) on google_cloud_bigquery::query::SqlValue and spells google_cloud_bigquery::query::{FromSql, SqlValue} and google_cloud_bigquery::error::ConvertError without leading ::.
    • Using dot-call syntax (row.take(...), value.take(...)) on unprefixed row / value locals instead of fully qualified function calls in __private freezes user-facing method signatures and risks method-resolution ambiguity if an in-scope extension trait defines .take(...).
    • Generated impl blocks are not enclosed in const _: () = { ... };.
  3. Crate-level rustdoc on google-cloud-bigquery-derive publishes maintainer policy:
    • src/bigquery-derive/src/lib.rs uses //! doc comments for internal # Compatibility / ## Contract tests CI instructions instead of // comments, and does not advise users to import FromRow / FromSql from google_cloud_bigquery::query rather than depending on google-cloud-bigquery-derive directly.
  4. Version skew note from #7424:
    • #7424 bumped google-cloud-bigquery from 0.19.0 to 1.0.0 while leaving google-cloud-bigquery-derive at 0.2.0. When migrating google-cloud-bigquery-derive to call ::google_cloud_bigquery::__private, google-cloud-bigquery-derive must also take a breaking bump (0.3.0 or 1.0.0) so google-cloud-bigquery 0.19.0 (which depends on ^0.2.0) does not resolve a 0.2.x patch release that references __private.
Expected Behavior
  • Add #[doc(hidden)] pub mod __private at the root of google-cloud-bigquery exposing only the internal types, traits, re-exports (Result, TryFrom), and helper functions needed by google-cloud-bigquery-derive.
  • Remove SqlValue from google_cloud_bigquery::query's public exports.
  • Keep google_cloud_bigquery::query::FromSql publicly nameable as a trait bound (for Row::get<T: FromSql>, Row::take<T: FromSql>, and generic callers), while sealing it / moving from_value onto a #[doc(hidden)] supertrait in __private so manual external implementations are prevented at the type/doc level rather than only by a prose warning.
  • Update google-cloud-bigquery-derive to emit const _: () = { ... }; blocks referencing only ::core::... / ::google_cloud_bigquery::__private::... via fully qualified function calls.
  • Convert the maintainer # Compatibility section in src/bigquery-derive/src/lib.rs from //! to // comments and add brief user-facing crate docs pointing to google_cloud_bigquery::query::{FromRow, FromSql}.
  • Take a breaking version bump on google-cloud-bigquery-derive alongside google-cloud-bigquery 1.0.0.
Ngôn ngữ chính
Rust
Star
972
Fork
163
Merge trung bình
1 ngày 13 giờ
Pull request đã merge (30 ngày)
202

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của googleapis/google-cloud-rust

Tất cả issue của googleapis/google-cloud-rust

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.