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

Open
  • Is something wrong?
#7,449 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
42/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
rust
Domain
api, backend

Research direction

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.

Written by the indexing model from the issue text.

Description

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.
Dominant language
Rust
Stars
972
Forks
163
Avg merge
1d 13h
Merged PRs (30d)
202

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from googleapis/google-cloud-rust

All issues in googleapis/google-cloud-rust

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.