chore: initial GEMINI.md file

GEMINI.md

@@ -0,0 +1,153 @@
+# Gemini Code Understanding
+
+## Project Overview
+
+This project provides idiomatic Rust client libraries for Google Cloud Platform
+(GCP) services. The goal is to offer a natural and familiar API for Rust
+developers to interact with GCP. The libraries are under active development, and
+the APIs are subject to change.
+
+The project is structured as a Rust workspace, containing numerous crates. Most
+of the client libraries are auto-generated from Protobuf service specifications.
+The core components include:
+
+- **Generated Libraries:** Located in `src/generated`, these are the
+  auto-generated client libraries for various GCP services.
+- **Authentication:** The `src/auth` crate handles authentication with Google
+  Cloud.
+- **GAX (Google API Extensions):** The `src/gax` crate provides common
+  components for all clients, including error handling, retry policies, and
+  backoff strategies. `src/gax-internal` contains implementation details shared
+  across clients.
+- **Long-Running Operations (LRO):** The `src/lro` crate provides support for
+  handling long-running operations.
+- **Well-Known Types (WKT):** The `src/wkt` crate contains shared types used
+  across the libraries.
+- **Cloud Storage:** The `src/storage` crate contains a client library for
+  Google Cloud Storage.
+
+## Building and Running
+
+The project uses Cargo, the Rust build tool and package manager.
+
+### Building the Project
+
+To build the entire workspace, run the following command from the root
+directory:
+
+```bash
+cargo build
+```
+
+### Running Tests
+
+To run the tests for the entire workspace, use the following command:
+
+```bash
+cargo test
+```
+
+To run the linter for a particular crate, use the following command:
+
+```bash
+cargo test -p ${crate_name}
+```
+
+For example:
+
+```bash
+cargo test -p google-cloud-storage
+```
+
+The integration tests, located in `src/integration-tests`, run against live GCP
+services to validate the generated code.
+
+### Linter
+
+To run the linter for the entire workspace, use the following command:
+
+```bash
+cargo clippy
+```
+
+To run the linter for a particular crate, use the following command:
+
+```bash
+cargo clippy -p ${crate_name}
+```
+
+For example:
+
+```bash
+cargo clippy -p google-cloud-storage
+```
+
+### Code Formatter
+
+To format the code for the entire workspace, use the following command:
+
+```bash
+cargo fmt
+```
+
+To format a crate use:
+
+```bash
+cargo fmt -p ${crate_name}
+```
+
+For example:
+
+```bash
+cargo fmt -p google-cloud-storage
+```
+
+## Development Conventions
+
+### Setting up the Development Environment
+
+- Install `rustc`, `rustfmt`, `clippy`, and `cargo` using `rustup`.
+- Run `cargo build` and `cargo test` to verify the setup.
+
+### Forks and Pull Requests
+
+- Create a fork of the `google-cloud-rust` repository.
+- Create a branch for your changes.
+- Make your changes and commit them with a descriptive message.
+- The commit message should follow the "Conventional Commits" specification.
+- Push your changes to your fork.
+- Create a pull request from your fork to the `main` branch of the
+  `google-cloud-rust` repository.
+- The PR body should include a detailed description of the changes.
+- The PR will be reviewed by the maintainers.
+
+### Generated Code Maintenance
+
+- Most of the code is generated by the `sidekick` tool.
+- Do not edit the generated code directly.
+- To update the generated code, you need to modify the generator templates or
+  the service definitions.
+
+### Asynchronous Programming
+
+All remote procedure calls (RPCs) are asynchronous and are designed to work with
+the Tokio runtime.
+
+### Error Handling
+
+The libraries provide robust error handling, with a focus on providing clear and
+actionable error messages.
+
+### Retry and Polling Policies
+
+The libraries include configurable policies for retrying failed requests and for
+polling the status of long-running operations. These policies can be customized
+by the application.
+
+### Contribution Guidelines
+
+Contributions are welcome. The `CONTRIBUTING.md` file provides detailed
+instructions for contributors. Key documents for contributors include:
+
+- `doc/contributor/howto-guide-set-up-development-environment.md`
+- `ARCHITECTURE.md`