Update AGENTS.md with pre-submission check instruction (#2792)

* [agents] Add pre-submission checks and instructions

* [agents] Add more instructions, rewrap comments

* [agents] Add more advice

* Undo wrapping of compiler output

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: Joshua Liebow-Feeser <[email protected]>

Author: google-labs-jules[bot]

AGENTS.md

@@ -41,3 +41,32 @@ Clippy should **always** be run on the `nightly` toolchain.
 # Run a specific test on stable
 ./cargo.sh +stable test -- test_name
 ```
+
+## Workflow
+
+### Pre-submission Checks
+
+Before submitting code, run `./githooks/pre-push` to confirm that all pre-push hooks succeed.
+
+### UI Tests
+
+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`.
+
+## Code Style
+
+### 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).

src/error.rs

@@ -897,8 +897,9 @@ impl<Src, Dst: ?Sized + TryFromBytes> From<CastError<Src, Dst>> for TryCastError
 
 /// The error type of fallible read-conversions.
 ///
-/// Fallible read-conversions, like [`TryFromBytes::try_read_from_bytes`] may emit
-/// [size](SizeError) and [validity](ValidityError) errors, but not alignment errors.
+/// Fallible read-conversions, like [`TryFromBytes::try_read_from_bytes`] may
+/// emit [size](SizeError) and [validity](ValidityError) errors, but not
+/// alignment errors.
 // Bounds on generic parameters are not enforced in type aliases, but they do
 // appear in rustdoc.
 #[allow(type_alias_bounds)]

src/macros.rs

@@ -1204,7 +1204,8 @@ mod tests {
         // that we do on and after 1.61.0.
         #[cfg(not(zerocopy_generic_bounds_in_const_fn_1_61_0))]
         {
-            // Test that `transmute_ref!` supports non-`KnownLayout` `Sized` types.
+            // Test that `transmute_ref!` supports non-`KnownLayout` `Sized`
+            // types.
             const ARRAY_OF_NKL_U8S: Nkl<[u8; 8]> = Nkl([0u8, 1, 2, 3, 4, 5, 6, 7]);
             const ARRAY_OF_NKL_ARRAYS: Nkl<[[u8; 2]; 4]> = Nkl([[0, 1], [2, 3], [4, 5], [6, 7]]);
             const X_NKL: &Nkl<[[u8; 2]; 4]> = transmute_ref!(&ARRAY_OF_NKL_U8S);
@@ -1223,7 +1224,8 @@ mod tests {
                 transmute_ref!(t)
             }
 
-            // Test that `transmute_ref!` supports non-`KnownLayout` `Sized` types.
+            // Test that `transmute_ref!` supports non-`KnownLayout` `Sized`
+            // types.
             const ARRAY_OF_NKL_U8S: Nkl<[u8; 8]> = Nkl([0u8, 1, 2, 3, 4, 5, 6, 7]);
             const ARRAY_OF_NKL_ARRAYS: Nkl<[[u8; 2]; 4]> = Nkl([[0, 1], [2, 3], [4, 5], [6, 7]]);
             const X_NKL: &Nkl<[[u8; 2]; 4]> = transmute_ref(&ARRAY_OF_NKL_U8S);
@@ -1571,9 +1573,10 @@ mod tests {
 
             cryptocorrosion_derive_traits! {
                 #[repr(C)]
-                /// Generic wrapper for unparameterized storage of any of the possible impls.
-                /// Converting into and out of this type should be essentially free, although it may be more
-                /// aligned than a particular impl requires.
+                /// Generic wrapper for unparameterized storage of any of the
+                /// possible impls. Converting into and out of this type should
+                /// be essentially free, although it may be more aligned than a
+                /// particular impl requires.
                 #[allow(non_camel_case_types)]
                 #[derive(Copy, Clone)]
                 pub union vec128_storage {

src/pointer/inner.rs

@@ -56,8 +56,9 @@ mod _def {
         ///   the set of addresses of an allocated object:
         ///   ...
         ///   - It is guaranteed that, given `o = a - base` (i.e., the offset of
-        ///     `a` within the allocated object), `base + o` will not wrap around
-        ///     the address space (in other words, will not overflow `usize`)
+        ///     `a` within the allocated object), `base + o` will not wrap
+        ///     around the address space (in other words, will not overflow
+        ///     `usize`)
         ptr: NonNull<T>,
         // SAFETY: `&'a UnsafeCell<T>` is covariant in `'a` and invariant in `T`
         // [1]. We use this construction rather than the equivalent `&mut T`,

src/pointer/ptr.rs

@@ -389,8 +389,8 @@ mod _conversions {
             // SAFETY:
             // - This cast is a no-op, and so trivially preserves address,
             //   referent size, and provenance
-            // - It is trivially sound to have multiple `&T` referencing the same
-            //   referent simultaneously
+            // - It is trivially sound to have multiple `&T` referencing the
+            //   same referent simultaneously
             // - By `T: TransmuteFromPtr<T, I::Aliasing, I::Validity, V>`, it is
             //   sound to perform this transmute.
             let ptr = unsafe { self.transmute_unchecked(SizeEq::cast_from_raw) };
@@ -807,9 +807,9 @@ mod _transitions {
             I::Aliasing: Reference,
             I: Invariants<Validity = Initialized>,
         {
-            // This call may panic. If that happens, it doesn't cause any soundness
-            // issues, as we have not generated any invalid state which we need to
-            // fix before returning.
+            // This call may panic. If that happens, it doesn't cause any
+            // soundness issues, as we have not generated any invalid state
+            // which we need to fix before returning.
             if T::is_bit_valid(self.reborrow().forget_aligned()) {
                 // SAFETY: If `T::is_bit_valid`, code may assume that `self`
                 // contains a bit-valid instance of `T`. By `T:

src/util/macro_util.rs

@@ -774,18 +774,19 @@ impl<'a, Src, Dst> Wrap<&'a Src, &'a Dst> {
         let src: *const Src = self.0;
         let dst = src.cast::<Dst>();
         // SAFETY:
-        // - We know that it is sound to view the target type of the input reference
-        //   (`Src`) as the target type of the output reference (`Dst`) because the
-        //   caller has guaranteed that `Src: IntoBytes`, `Dst: FromBytes`, and
-        //   `size_of::<Src>() == size_of::<Dst>()`.
+        // - We know that it is sound to view the target type of the input
+        //   reference (`Src`) as the target type of the output reference
+        //   (`Dst`) because the caller has guaranteed that `Src: IntoBytes`,
+        //   `Dst: FromBytes`, and `size_of::<Src>() == size_of::<Dst>()`.
         // - We know that there are no `UnsafeCell`s, and thus we don't have to
-        //   worry about `UnsafeCell` overlap, because `Src: Immutable` and `Dst:
-        //   Immutable`.
+        //   worry about `UnsafeCell` overlap, because `Src: Immutable` and
+        //   `Dst: Immutable`.
         // - The caller has guaranteed that alignment is not increased.
-        // - We know that the returned lifetime will not outlive the input lifetime
-        //   thanks to the lifetime bounds on this function.
+        // - We know that the returned lifetime will not outlive the input
+        //   lifetime thanks to the lifetime bounds on this function.
         //
-        // FIXME(#67): Once our MSRV is 1.58, replace this `transmute` with `&*dst`.
+        // FIXME(#67): Once our MSRV is 1.58, replace this `transmute` with
+        // `&*dst`.
         #[allow(clippy::transmute_ptr_to_ref)]
         unsafe {
             mem::transmute(dst)
@@ -794,8 +795,8 @@ impl<'a, Src, Dst> Wrap<&'a Src, &'a Dst> {
 }
 
 impl<'a, Src, Dst> Wrap<&'a mut Src, &'a mut Dst> {
-    /// Transmutes a mutable reference of one type to a mutable reference of another
-    /// type.
+    /// Transmutes a mutable reference of one type to a mutable reference of
+    /// another type.
     ///
     /// # PME
     ///

src/util/macros.rs

@@ -342,9 +342,10 @@ macro_rules! opt_unsafe_fn {
 /// assumption that the impl emitted by the custom derive is sound).
 ///
 /// The caller is still required to provide a safety comment (e.g. using the
-/// `const _: () = unsafe` macro) . The reason for this restriction is that, while
-/// `impl_or_verify!` can guarantee that the provided impl is sound when it is
-/// compiled with the appropriate cfgs, there is no way to guarantee that it is
+/// `const _: () = unsafe` macro). The reason for this restriction is that,
+/// while `impl_or_verify!` can guarantee that the provided impl is sound when
+/// it is compiled with the appropriate cfgs, there is no way to guarantee that
+/// it is
 /// ever compiled with those cfgs. In particular, it would be possible to
 /// accidentally place an `impl_or_verify!` call in a context that is only ever
 /// compiled when the `derive` feature is disabled. If that were to happen,

src/util/mod.rs

@@ -146,7 +146,8 @@ pub(crate) const fn padding_needed_for(len: usize, align: NonZeroUsize) -> usize
     #[allow(clippy::arithmetic_side_effects)]
     let mask = align.get() - 1;
 
-    // To efficiently subtract this value from align, we can use the bitwise complement.
+    // To efficiently subtract this value from align, we can use the bitwise
+    // complement.
     // Note that ((!len) & (align-1)) gives us a number that with (len &
     // (align-1)) sums to align-1. So subtracting 1 from x before taking the
     // complement subtracts `len` from `align`. Some quick inspection of
@@ -177,7 +178,8 @@ pub(crate) const fn padding_needed_for(len: usize, align: NonZeroUsize) -> usize
     //
     // (declare-const len (_ BitVec 32))
     // (declare-const align (_ BitVec 32))
-    // ; Search for a case where align is a power of two and padding2 disagrees with padding1
+    // ; Search for a case where align is a power of two and padding2 disagrees
+    // ; with padding1
     // (assert (and (is-power-of-two align)
     //              (not (= (padding1 len align) (padding2 len align)))))
     // (simplify (padding1 (_ bv300 32) (_ bv32 32))) ; 20
@@ -602,8 +604,9 @@ pub(crate) use len_of::MetadataOf;
 /// exist (stably) on our MSRV. This module provides polyfills for those
 /// features so that we can write more "modern" code, and just remove the
 /// polyfill once our MSRV supports the corresponding feature. Without this,
-/// we'd have to write worse/more verbose code and leave FIXME comments sprinkled
-/// throughout the codebase to update to the new pattern once it's stabilized.
+/// we'd have to write worse/more verbose code and leave FIXME comments
+/// sprinkled throughout the codebase to update to the new pattern once it's
+/// stabilized.
 ///
 /// Each trait is imported as `_` at the crate root; each polyfill should "just
 /// work" at usage sites.

zerocopy-derive/src/enum.rs

@@ -162,8 +162,8 @@ fn generate_variants_union(generics: &Generics, data: &DataEnum) -> TokenStream
             return None;
         }
 
-        // Field names are prefixed with `__field_` to prevent name collision with
-        // the `__nonempty` field.
+        // Field names are prefixed with `__field_` to prevent name collision
+        // with the `__nonempty` field.
         let field_name_str = crate::ext::to_ident_str(&variant.ident);
         let field_name = Ident::new(&format!("__field_{}", field_name_str), variant.ident.span());
         let variant_struct_ident = variant_struct_ident(&variant.ident);