Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (90 loc) · 7.03 KB

AGENTS.md

File metadata and controls

104 lines (90 loc) · 7.03 KB
Raw

AGENTS.md

Codex PR Review Rules

Apply these rules to all new or materially modified code and documentation in this repository. Do not churn unrelated legacy lines solely to satisfy this file; keep legacy style unless the surrounding work is already touching that area.

  1. Units on numeric literals

    • Add a trailing inline unit comment to each numeric literal assignment/definition when the quantity has physical meaning.
    • Physical quantities include time, length, mass, angle, rate, force, torque, voltage/current, inertia, and similar engineering values.
    • Keep the unit immediately adjacent to the value, typically as an inline comment such as value = 1.2 # [s].
    • The exact unit spelling is not important if the unit is clear. Accept common forms such as [N*m], [Nm], Nm, [kg*m^2], [kg m^2], [m/s^2], and [rad/s].
    • Do not flag reasonable unit spellings solely for formatting differences; focus on whether units are present and understandable.
    • Use [-] for dimensionless physical values when it improves clarity, but do not require unit comments for obvious pure math literals or all-zero/identity initializers.
    • Unit comments are not required for indexes, counters, array sizes/shapes, loop ranges, flags, enum/status values, random seeds, test case identifiers, non-physical plotting/layout constants, or other clearly non-physical values.
    • For dense arrays, tables, or function calls, document units once on the variable, column, or argument when per-element comments would hurt readability.

  2. Documentation and doc-comment format

    • New or updated Python docstrings and standalone .rst documentation must use valid, well-formed reStructuredText that renders correctly with Sphinx.
    • New or updated C/C++ API comments must use valid Doxygen syntax that produces the expected Doxygen XML and renders correctly through Breathe/Sphinx.
    • In C/C++ Doxygen comments, use Doxygen commands such as @brief, @param, @return, and @note. The @param command is the correct way to make method parameters appear in the generated API documentation; do not require reStructuredText field lists such as :param name: in C/C++ header comments.
    • Ensure every documented parameter name matches the declaration and that parameter, return, and note sections are complete and renderable in the documentation pipeline.

  3. Spelling quality

    • No misspellings in newly added/modified identifiers, comments, docstrings, Doxygen blocks, user-facing strings, or docs text.

  4. Coding-guideline conformance

    • New code must follow Basilisk coding guidelines in: docs/source/Support/Developer/CodingGuidlines.rst.
    • Respect language-specific foundations referenced there (C/C++: Stroustrup/Sutter style basis; Python: PEP 8), plus Basilisk naming and message conventions.
    • For legacy non-conforming files: keep style consistent for minor edits; use major refactors to move code toward guideline compliance.
    • Follow the checkout recommendation in docs/source/Support/Developer/bskModuleCheckoutList.rst

  5. MRP attitude typing

    • For new or modified C++ code, use Eigen::MRPd for values that semantically represent Modified Rodrigues Parameter attitudes, such as sigma_* attitude variables, state values, properties, and function parameters.
    • Avoid using generic Eigen::Vector3d for MRP attitudes unless the code is crossing a boundary that requires raw vector storage, such as message payloads, C arrays, state/property containers, SWIG/Python-facing initialization fields, or generic math APIs.
    • Prefer MRP-specific helpers and methods, such as cArray2EigenMRPd, eigenMRPd2CArray, .coeffs(), .Bmat(), .toRotationMatrix(), and .shadow(), instead of casting MRPs through Eigen::Vector3d.
    • Do not convert unrelated three-component physical vectors, such as position, velocity, acceleration, angular rate, force, torque, or magnetic field vectors, to Eigen::MRPd.

  6. String and logging security review

    • For new or modified C/C++ code, check for unsafe writes to fixed-size C buffers, including strcpy, strcat, sprintf, unbounded %s scans, and strncpy uses that can silently truncate or omit null termination.
    • Prefer bounded formatting/copying APIs such as snprintf with sizeof(destination) when writing to fixed-size buffers.
    • If a user- or module-supplied string is too long for a fixed-size Basilisk payload field, emit BSK_ERROR so execution stops immediately rather than silently truncating.
    • For bskLog() and other printf-style logging calls, ensure the format string is a string literal. Dynamic text must be passed through a literal format such as "%s".
    • When a PR fixes one instance of a buffer-write or format-string issue, search nearby BSK modules and related payload paths for the same pattern and flag or fix matching issues.

  7. PR metadata requirements

    • Follow docs/source/Support/bskReleaseNotesSnippets/README.md for when a release-note snippet is required and how snippet files should be formatted.
    • Update docs/source/Support/bskKnownIssues.rst when a PR fixes, changes, or documents a known user-visible issue or workaround.

  8. SysModel documentation requirement

    • Every new SysModel must include a corresponding .rst documentation file.
    • Pattern new module docs after: src/moduleTemplates/cModuleTemplate/cModuleTemplate.rst or src/moduleTemplates/cppModuleTemplate/cppModuleTemplate.rst.
    • For new or modified BSK module .rst files, ensure module input/output message documentation uses the .. bsk-module-io:: directive rather than hand-written module I/O tables or standalone module I/O SVG images.

  9. Basilisk Module Creation

    • Ensure new Basilisk modules have a unit test
    • Unit test method needs to have documentation strings
    • Ensure the copyright statement is in new files using the current year

  10. Basilisk Example Files

  • If an example scenario is included in the examples folder, ensure this example has a unit test in src/tests that imports and runs this example file.
  • If the example file includes the enableUnityVisualization() method, ensure the saveFile argument is included but commented out.
  • Ensure new Python example scripts are linked in examples/_default.rst.
  • Ensure any data importing is done in a robust manner supporting Linux, Windows and macOS
  1. Header self-containment
  • For every new or materially modified C/C++ header, verify that it directly includes the headers required for every type, function, and macro it uses.
  • Do not rely on transitive includes or include order.
  • Where practical, compile the header in isolation using its owning target's build flags.
  • Pay particular attention to fixed-width integer types, Eigen types, messaging types, and BSKLogger.
  • Exempt intentional implementation fragments, generated headers, and SWIG-only include files when standalone compilation is not appropriate.