googleapis / googleapis/google-cloud-rust
refactor(gce): separate hand-crafted code from `src/generated/` to improve review safety
- 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
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