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

Abierto
  • ¿Algo no está bien?
#7,449 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
42/100
Tipo de issue
Refactorización
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
rust
Área
api, backend

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
Rust
Estrellas
972
Forks
163
Merge medio
1 d 13 h
PR fusionados (30 d)
202

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de googleapis/google-cloud-rust

Todos los issues de googleapis/google-cloud-rust

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.