googleapis / googleapis/google-cloud-rust

refactor(gce): separate hand-crafted code from `src/generated/` to improve review safety

Open
#5,994 0 comments 0 reactions 0 assignees View on GitHub
priority: p3 type: feature request
Dominant language
Rust
Stars
955
Forks
144
Avg merge
1d 5h
Merged PRs (30d)
279

Description

**Is your feature request related to a problem? Please describe.**
Hand-crafted files (such as Compute Engine's `errors.rs` and `operation.rs`) live directly inside the `src/generated/` directory structure. The problem with that is: reviewers who see changes under paths containing `generated/` may assume it is just the output of a routine `librarian` version update and rubber-stamp the PR without a thorough review of the manual logic changes.

**Describe the solution you'd like**
I'd like a repository-wide convention to clearly signal human-authored files inside generated packages.

#### **Option A: Local Crate `handwritten/` Subdirectory (Recommended)**
Move the manual files into a `handwritten/src` directory that sits alongside the crate's `src/` directory (e.g., `src/generated/cloud/compute/v1/handwritten/src/operation.rs`).
* The module is imported in `src/lib.rs` using relative path:
```rust
#[allow(missing_docs)]
#[path = "../handwritten/src/operation.rs"]
pub mod operation;
```
* The files are kept during generation by referencing them in `librarian.yaml`:
```yaml
keep:
- handwritten/errors.rs
- handwritten/operation.rs
```

#### **Option B: Suffixing Files with `_handwritten`**
Keep the files in `src/` but rename them to explicitly include a `_handwritten` suffix (e.g., `src/generated/cloud/compute/v1/src/operation_handwritten.rs`).
* The module is imported in `src/lib.rs` with `#[path]` to preserve the public module name for API stability:
```rust
#[allow(missing_docs)]
#[path = "operation_handwritten.rs"]
pub mod operation;
```
* The files are kept during generation via `librarian.yaml`:
```yaml
keep:
- src/errors_handwritten.rs
- src/operation_handwritten.rs
```

Both options maintain 100% backwards-compatibility for library consumers (the public API still exposes `pub mod errors` and `pub mod operation` unchanged).

**Describe alternatives you've considered**
We also considered moving files entirely outside of the `src/generated/` parent folder to a global repository root (e.g. `src/handwritten/cloud/compute/...`), but rejected it because Rust's `#[path]` attribute does not support macro resolution (like `env!("CARGO_MANIFEST_DIR")`), meaning it requires deeply nested, brittle relative path traversals (like `../../../../../`).

**Additional context**
This confusion recently surfaced during the review of [PR #5955](https://github.com/googleapis/google-cloud-rust/pull/5955), where manual telemetry mappings were added to `src/generated/cloud/compute/v1/src/operation.rs`. I was surprised to see manual logic changes in a `generated` path until it was clarified that the file is preserved via the `keep:` list in `librarian.yaml`.

Contributor guide

Open the contributing guide

Research direction

Start with the Compute Engine files under src/generated/cloud/compute/v1/, especially src/lib.rs, the hand-crafted errors.rs and operation.rs, and their librarian.yaml keep entries. Compare the handwritten/ layout with the _handwritten suffix option across the repository and review PR #5955 for context. Done means a repository-wide convention is chosen and applied while generation preserves the files and the public errors and operation modules remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.