Skip to content

Prefer full names over aliases for crate dependencies #4598

@coryan

Description

@coryan

In a number of places we use aliases for crate names, such as gax instead of google-cloud-gax. That saves us typing, but produces examples that may be confusing: where we use gax::error::Error instead of google_cloud_gax::error::Error the reader may wonder what gax is, and may even find a bad crate.

Likewise, the source code buttons at docs.rs are less useful if there are a lot of aliases to keep in ones head.

I removed most aliases without filing a bug (tsck, tsck). But it is time to explain why we are doing this. The remaining crates are google-cloud-gax, google-cloud-gax-internal and google-cloud-wkt.

The outline is:

  • Add some pub(crate) use google_cloud_gax::Foo; use declarations to simplify the generated code.
  • Generate the code with crate::Foo; everywhere.
  • Use google-cloud-gax in storage, pubsub, firestore, and the generated clients.
  • Add conditional pub(crate) use google_cloud_gax::Bar; use declarations for pagination.
  • Use these declarations in the generated code.
  • Add some pub(crate) use google_cloud_gax_internal::Bar; use declarations to simplify the generated code.
  • Use crate::Bar everywhere.
  • Use google-cloud-gax-internal in storage, pubsub, firestore and the generated clients.
  • Add some pub(crate) use google_cloud_wkt::internal::Bar; use declarations to crate::internal.
  • Change the generated code to say crate::internal instead of wkt::internal
  • Add the minimum set of google_cloud_wkt::* declarations to (a new pub(crate) module) crate::wkt.
  • Change the generated code to say crate::wkt instead of wkt.

Keeping all the new symbols pub(crate) would allow changes later, in case we decide that they should all be in a sub-module, or in the root module, or some other alternative.

Metadata

Metadata

Assignees

No one assigned

    Labels

    type: cleanupAn internal cleanup or hygiene concern.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions