Add more instructions for coding agents (#2834)

gherrit-pr-id: Icc2e26ad2a5c67a16f328a605b5821e36dbb343f

Author: joshlf

.gemini/styleguide.md

@@ -8,4 +8,10 @@ those terms. -->
 
 # Coding Guidelines
 
-Please follow the development instructions and coding guidelines defined in `AGENTS.md` located in the root of this repository.
+Please follow the development instructions and coding guidelines defined in
+`AGENTS.md` and `CONTRIBUTING.md` files located in the root of this repository.
+
+> [!IMPORTANT]
+> **READ `AGENTS.md` FIRST.**
+> All critical instructions, including build commands, safety rules, and code
+> style, are defined in `AGENTS.md`. You must read and follow them.

AGENTS.md

@@ -6,100 +6,67 @@ license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
 This file may not be copied, modified, or distributed except according to
 those terms. -->
 
-# Development Instructions
+# Instructions for AI Agents
 
-This repository uses a wrapper script around Cargo to ensure consistent toolchain usage and configuration.
+## Agent Persona & Role
 
-## Build and Test
+You are an expert Rust systems programmer contributing to **zerocopy**, a
+library for zero-cost memory manipulation which presents a safe API over what
+would otherwise be dangerous operations. Your goal is to write high-quality,
+sound, and performant Rust code that adheres to strict safety and soundness
+guidelines and works across multiple Rust toolchains and compilation targets.
 
-**IMPORTANT:** You must **NEVER** run `cargo` directly. Instead, you must **ALWAYS** use `yes | ./cargo.sh` for all `cargo` sub-commands (e.g., `check`, `test`, `build`). Using `yes |` is required to bypass interactive prompts for toolchain installation.
+## Critical Rules
 
-### Syntax
-`yes | ./cargo.sh +<toolchain> <command> [args]`
+- **README Generation:** **DON'T** edit `README.md` directly. It is generated
+  from `src/lib.rs`. Edit the top-level doc comment in `src/lib.rs` instead.
+  - **To regenerate:**
+    `./cargo.sh +stable run --manifest-path tools/generate-readme/Cargo.toml > README.md`
 
-### Toolchains
-The `<toolchain>` argument is mandatory and can be one of the following:
+<!-- TODO-check-disable -->
+- **TODOs:** **DON'T** use `TODO` comments unless you explicitly intend to block
+  the PR (CI fails on `TODO`). Use `FIXME` for non-blocking issues.
+<!-- TODO-check-enable -->
 
-- `msrv`: Runs with the Minimum Supported Rust Version.
-- `stable`: Runs with the stable toolchain.
-- `nightly`: Runs with the nightly toolchain.
-- `all`: Runs the command on `msrv`, `stable`, and `nightly` sequentially.
-- Version-gated toolchains: You can also pass specific version-gated toolchains defined in `Cargo.toml`, such as `zerocopy-core-error-1-81-0`.
+- **Documentation:** **DO** ensure that changes do not cause documentation to
+  become out of date (e.g., renaming files referenced here).
 
-### Linting
+## Project Context
 
-Clippy should **always** be run on the `nightly` toolchain.
+### Overview
 
-```bash
-yes | ./cargo.sh +nightly clippy
-yes | ./cargo.sh +nightly clippy --tests
-```
+Zerocopy is a library designed to make zero-copy memory manipulation safe and
+easy. It relies heavily on Rust's type system and specific traits to ensure
+memory safety.
 
-### Examples
+### Project Structure
 
-```bash
-# Check the code using the nightly toolchain
-# DO NOT RUN: cargo check
-yes | ./cargo.sh +nightly check
+- `src/`: Core library source code.
+- `zerocopy-derive/`: Source code and tests for the procedural macros.
+- `tests/`: UI and integration tests for the main crate.
+- `tools/`: Internal tools and scripts.
+- `ci/`: CI configuration and scripts.
+- `githooks/`: Git hooks for pre-commit/pre-push checks.
+- `testdata/`: Data used for testing.
+- `testutil/`: Utility code for tests.
 
-# Run tests on all supported toolchains
-# DO NOT RUN: cargo test
-yes | ./cargo.sh +all test
+## Development Workflow
 
-# Run a specific test on stable
-yes | ./cargo.sh +stable test -- test_name
-```
+When developing code changes, you **MUST** read
+[agent_docs/development.md](./agent_docs/development.md).
 
-## Workflow
+### Before submitting
 
-### Pre-submission Checks
+Once you have made a change, you **MUST** read the relevant documents to ensure
+that your change is valid and follows the style guidelines.
 
-Before submitting code, run `./githooks/pre-push` to confirm that all pre-push hooks succeed.
+- [agent_docs/validation.md](./agent_docs/validation.md) for validating code
+  changes
+- [agent_docs/style.md](./agent_docs/style.md) for style and formatting
+  guidelines for files and commit messages
 
-### UI Tests
+#### Pre-submission Checks
 
-When updating UI test files (in `tests/ui*` or `zerocopy-derive/tests/ui*`), run `./tools/update-ui-test-files.sh` to update the corresponding stderr files.
-
-### Pull Requests and Commit Messages
-
-When a PR resolves an issue, the PR description and commit message should include a line like `Closes #123`.
-When a PR makes progress on, but does not close, an issue, the PR description and commit message should include a line like `Makes progress on #123`.
-
-## Safety
-
-### Pointer Casts
-
-- **Avoid `&slice[0] as *const T` or `&slice[0] as *mut T`.**
-  Instead, use `slice.as_ptr()` or `slice.as_mut_ptr()`. Casting a reference to
-  a single element creates a raw pointer that is only valid for that element.
-  Accessing subsequent elements via pointer arithmetic is Undefined Behavior.
-  See [unsafe-code-guidelines#134](https://github.com/rust-lang/unsafe-code-guidelines/issues/134).
-
-- **Avoid converting `&mut T` to `*const T` (or `*const U`)**.
-  This advice applies if you intend to later cast the pointer to `*mut T` and
-  mutate the data. This conversion reborrows `&mut T` as a shared reference
-  `&T`, which may restrict permissions under Stacked Borrows. Instead, cast
-  `&mut T` directly to `*mut T` first, then to `*const T` if necessary. See
-  [rust#56604](https://github.com/rust-lang/rust/issues/56604).
-
-## Code Style
-
-### File Headers
-
-Each file should contain a copyright header (excluding auto-generated files such as `.stderr` files). The header should follow the format found in existing files (e.g. `src/lib.rs`), using the appropriate comment syntax for the file type.
-
-### Formatting
-
-To determine how to format code, read the formatting checker script in `ci/check_fmt.sh`.
-
-### Comments
-
-All comments (including `//`, `///`, and `//!`) should be wrapped at 80 columns.
-
-**Exceptions:**
-- Markdown tables
-- Inline ASCII diagrams
-- Long URLs
-- Comments inside of code blocks
-- Comments which trail non-comment code
-- Other cases where wrapping would significantly degrade readability (use your judgment).
+Run `./githooks/pre-push` before submitting. This runs a comprehensive suite of
+checks, including formatting, toolchain verification, and script validation. It
+catches many issues that would otherwise fail in CI.

Cargo.toml

@@ -16,9 +16,18 @@
 edition = "2021"
 name = "zerocopy"
 version = "0.8.31"
-authors = ["Joshua Liebow-Feeser <[email protected]>", "Jack Wrenn <[email protected]>"]
+authors = [
+    "Joshua Liebow-Feeser <[email protected]>",
+    "Jack Wrenn <[email protected]>",
+]
 description = "Zerocopy makes zero-cost memory manipulation effortless. We write \"unsafe\" so you don't have to."
-categories = ["embedded", "encoding", "no-std::no-alloc", "parsing", "rust-patterns"]
+categories = [
+    "embedded",
+    "encoding",
+    "no-std::no-alloc",
+    "parsing",
+    "rust-patterns",
+]
 keywords = ["cast", "convert", "transmute", "transmutation", "type-punning"]
 license = "BSD-2-Clause OR Apache-2.0 OR MIT"
 repository = "https://github.com/google/zerocopy"
@@ -35,6 +44,18 @@ exclude = [".*"]
 # Each name is suffixed with the version it corresponds to. This is a convention
 # used in the codebase to make it less likely for us to make mistakes when
 # writing `doc_cfg` attributes.
+#
+# It may seem odd to name cfgs `no-zerocopy-foo` and emit these cfgs on
+# toolchains lower than that target toolchain. We do this because it is
+# friendlier to users who compile zerocopy by directly invoking rustc or by
+# invoking rustc from a build system other than Cargo. If such a user provides
+# no `--cfg` arguments, then, assuming they are on a sufficiently recent
+# toolchain, everything will "just work" without requiring extra configuration.
+# See [1] for an example of a user upgrading from a version of zerocopy which
+# did things in the inverse way. See #2259 for more context.
+#
+# [1] https://fuchsia-review.googlesource.com/c/fuchsia/+/1433139/1/third_party/rust_crates/Cargo.toml
+
 
 # From 1.89.0, Rust supports x86 AVX-12 SIMD types (previously gated by the
 # `stdarch_x86_avx512` feature).
@@ -83,7 +104,12 @@ std = ["alloc"]
 # This feature depends on all other features that work on the stable compiler.
 # We make no stability guarantees about this feature; it may be modified or
 # removed at any time.
-__internal_use_only_features_that_work_on_stable = ["alloc", "derive", "simd", "std"]
+__internal_use_only_features_that_work_on_stable = [
+    "alloc",
+    "derive",
+    "simd",
+    "std",
+]
 
 [dependencies]
 zerocopy-derive = { version = "=0.8.31", path = "zerocopy-derive", optional = true }

agent_docs/development.md

@@ -0,0 +1,97 @@
+<!-- Copyright 2025 The Fuchsia Authors
+
+Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
+<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
+license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
+This file may not be copied, modified, or distributed except according to
+those terms. -->
+
+# Development Guidelines
+
+This document covers guidelines for developing code changes.
+
+## Build and Test
+
+This repository uses a wrapper script (`cargo.sh`) to ensure consistent
+toolchain usage and configuration.
+
+> [!IMPORTANT]
+> **NEVER** run `cargo` directly.
+> **ALWAYS** use `./cargo.sh` for all cargo sub-commands.
+>
+> **Why?** `cargo.sh` ensures that the toolchains used in development match
+> those in CI, which is important because some features are only available on
+> specific toolchains, and because UI tests rely on the text of compiler errors,
+> which changes between toolchain versions.
+
+### Syntax
+
+`./cargo.sh +<toolchain> <command> [args]`
+
+This is equivalent to:
+
+`cargo +1.2.3 <command> [args]`
+
+...where `1.2.3` is the toolchain version named by `<toolchain>` (e.g., `msrv` ->
+`1.56.0`).
+
+### Toolchains
+
+The `<toolchain>` argument is mandatory:
+- `msrv`: Minimum Supported Rust Version.
+- `stable`: Stable toolchain.
+- `nightly`: Nightly toolchain.
+- `all`: Runs on `msrv`, `stable`, and `nightly` sequentially.
+- Version-gated: e.g., `no-zerocopy-core-error-1-81-0` (see `Cargo.toml`).
+
+
+## MSRV (Minimum Supported Rust Version)
+
+The MSRV is **1.56.0**.
+
+- **Do NOT** use features stabilized after 1.56.0 unless version-gated.
+- **Requirement:** Ask for user approval before introducing new version-gated
+  behavior.
+- **Verify**: Ensure code compiles on 1.56.0 (`./cargo.sh +msrv ...`).
+
+### Version Gating Convention
+
+We use `[package.metadata.build-rs]` in `Cargo.toml` to gate features by Rust version.
+
+1.  **Define**: Add `no-zerocopy-<feature>-<version> = "<version>"` to `Cargo.toml`.
+2.  **Use**: Use `#[cfg(not(no_zerocopy_<feature>_<version>))]` (note underscores).
+3.  **Document**: For public items, use `#[cfg_attr(doc_cfg, doc(cfg(rust = "<version>")))]`.
+
+**Important:** The toolchains listed in `.github/workflows/ci.yml` and
+`Cargo.toml` (under `[package.metadata.build-rs]`) must be kept in sync. If you
+add a new version-gated feature, ensure it is reflected in both places.
+
+## UI Tests
+
+For advice on how to add, modify, or remove UI tests (in `tests/ui-*` or
+`zerocopy-derive/tests/ui-*`), refer to [agent_docs/ui_tests.md](./ui_tests.md).
+
+## Macro Development
+
+- **Shared Logic:** Put shared macro logic in `src/util/macro_util.rs` to avoid
+  code duplication in generated code.
+- **Lints:** Generated code often triggers lints. Use `#[allow(...)]` liberally
+  in generated code to suppress them.
+  ```rust
+  // GOOD: Suppress lints that might be triggered by generated names.
+  // Example: Using a variant name (PascalCase) as a field name (snake_case).
+  // Input: `enum MyEnum { VariantA }`
+  // Generated: `union Variants { __field_VariantA: ... }`
+  quote! {
+      #[allow(non_snake_case)]
+      union ___ZerocopyVariants {
+          #(#fields)*
+      }
+  }
+  ```
+
+## Unsafe Code
+
+`unsafe` code is extremely dangerous and should be avoided unless absolutely
+necessary. For guidelines on writing unsafe code, including pointer casts and
+safety comments, refer to [agent_docs/unsafe_code.md](./unsafe_code.md).

agent_docs/style.md

@@ -0,0 +1,45 @@
+<!-- Copyright 2025 The Fuchsia Authors
+
+Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
+<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
+license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
+This file may not be copied, modified, or distributed except according to
+those terms. -->
+
+# Style Guidelines
+
+This document covers code style and formatting guidelines for the project, as
+well as commit message requirements.
+
+## File Headers
+
+Each file must contain a copyright header (see `src/lib.rs` for example) which is
+based on that file's creation year.
+
+## Formatting
+
+Refer to `ci/check_fmt.sh`.
+
+## Comments
+
+- Wrap all comments (`//`, `///`, `//!`) at **80 columns** from the left margin,
+  taking into account any preceding code or comments.
+- **Exceptions:** Markdown tables, ASCII diagrams, long URLs, code blocks, or
+  other cases where wrapping would impair readability.
+
+## Markdown Files
+
+- Wrap paragraphs and bulleted lists at **80 columns** from the left margin,
+  taking into account any preceding code or comments. For example, a markdown
+  block inside of a `/// Lorem ipsum...` comment should have lines no more than
+  76 columns wide.
+  - In bulleted lists, indent subsequent lines by 2 spaces.
+  - Do not wrap links if it breaks them.
+- Always put a blank line between a section header and the beginning of the section.
+
+## Pull Requests and Commit Messages
+
+Use GitHub issue syntax in commit messages:
+
+- Resolves issue: `Closes #123`
+- Progress on issue: `Makes progress on #123`