diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6a13fab --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,60 @@ +## Outreachy Application Process + +These instructions are specifically for Outreachy Applicants in October 2026. + +IMPORTANT: You **must** only open one pull request (PR). + +### Banned AI Usage + +**Do not** use AI to write GitHub descriptions, GitHub comments, code comments, or Zulip chats. Write in your native language, or at your current English level. In your PR description, you must tell us how you used AI. You must review code yourself before you open a PR. + +For the best learning experience, write the code yourself, without using AI. + +Applicants must follow the [Rust Project AI/LLM policy][llm-policy]. + +[llm-policy]: https://blog.rust-lang.org/inside-rust/2026/08/05/rust-langrust-is-adopting-an-llm-policy/ + +### Application Steps + +Claim a C++ standard library type from the list [in the tracking issue][tracking-issue] by clicking on that issue, then commenting on it. This is the C++ type you will be working on. Before you claim a ticket, make sure no-one else has commented before you. + +After each step, push your work to your open PR, make sure CI passes, then **wait** for 2-4 days for a mentor to review it. If you need help, post a message in the [#outreachy > Overloading Applicant Help Oct 2026][outreachy-zulip] topic on Zulip. + +This coding task focuses on Rust and C++ overloads. It is ok to skip drop/destructors (leak memory), use unsafe, and ignore some compiler warnings. Shortcuts and workarounds can be used to simplify non-overload code. + +[tracking-issue]: https://github.com/rustfoundation/overloading-macros/issues/19 +[outreachy-zulip]: https://rust-lang.zulipchat.com/#narrow/channel/578347-outreachy/topic/Overloading.20Applicant.20Help.20Oct.202026/with/628605857.01 + +1. Write Rust wrappers for 3-5 C++ overloads on that type: + - [ ] Create a new file named after your type in [overloading-macros/cpp-overload-test/src/stdcpp](https://github.com/rustfoundation/overloading-macros/tree/main/cpp-overload-test/src/stdcpp) + - [ ] Wrap constructors first, writing tests to make sure the correct constructor is called + - [ ] Explain any potential compatibility issues in a `Limitations` doc section + - [ ] Explain usability issues in an `Ergonomics` doc section + - [ ] Push your changes and wait for a review +2. Add a separate example with some failing overloads + - [ ] Create a new file named after your type in [overloading-macros/cpp-overload-test/examples](https://github.com/rustfoundation/overloading-macros/tree/main/cpp-overload-test/examples) + - [ ] Wrap accessor/modifier methods + - [ ] Explain how they fail in an `Incompatibilities` doc section + - [ ] Explain how the overload failures could be resolved in a `Workarounds` doc section + - [ ] Optional: If there's a C++ feature with no equivalent in Rust, explain that in an `Inexpressible Overloads` doc section + - [ ] Push your changes and wait for a review +3. Update the [overload macro compatibility table Markdown doc](https://github.com/rustfoundation/overloading-macros/blob/main/cpp-overloads-in-rust.md) + - [ ] If you haven't checked some kinds of overloads, put a ？in those squares + - [ ] Push your changes and wait for a review + +Mark items in this checklist as done by clicking the box next to each item. + +#### Focus on Interesting Overloads + +Only wrap functions that have overloads. (It is ok to wrap non-overloaded functions just for testing.) + +Ignore these overloads: +- overloaded operators: they are already possible in Rust +- overloads with an allocator argument, or that only differ by `noexcept`: not an interesting difference +- assignment functions, assignment operators, and `swap`: no equivalent in Rust (which uses memcpy for assignment/swaps) + +Only code one example of overloads that: +- only differ by `const`/non-`const`, `&`/`&&` (or `&`/`&mut`) +- are iterator methods that only differ by position (`before_begin`/`begin`,`end`) + +You can look at [stdcpp/forward_list.rs (working overloads)](https://github.com/rustfoundation/overloading-macros/blob/main/cpp-overload-test/src/stdcpp/forward_list.rs) and [stdcpp-forward-list.rs (failing overloads)](https://github.com/rustfoundation/overloading-macros/blob/main/cpp-overload-test/examples/stdcpp-forward-list.rs) for example code. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61a8a64 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,237 @@ +# Agent instructions + +## LLM usage policy + +Follow the Rust project's [LLM usage policy]. It applies to all LLM-generated +text even if a human later edits it. + +[LLM usage policy]: https://forge.rust-lang.org/policies/llm-usage.html + +### When a gate fails + +When a rule identifies banned work, **STOP** that work. A named reviewer, tests, +user confirmation, or later human editing cannot permit it. Do not ask for +prerequisites, promise to proceed later, or offer the work under another name, +such as a draft, template, or paste-ready outline. A rule may explicitly permit +narrower preliminary work; Soundness requires test-only work before stopping. + +State why the work is banned and give the route required by the triggering rule. +Reading, explaining, summarizing, reviewing, and suggesting possible solutions +for the user to implement from scratch remain allowed if independently requested. +Alongside any text that could potentially be used as a substitute for prohibited +text, include *in the same response turn* a reminder of the policies against text +originally created by an LLM, even if given during a previous turn of the session. +Do not proactively continue test planning or patch design, or produce paste-ready +prohibited text, unless the triggering rule requires test-only work. + +### Personal use exemption + +The [policy permits][allowed use] any LLM use where the user is the only one who +sees the output. If the user states, in this conversation, that a change is for +personal use, prototyping, or experimentation with no intent to upstream the +change, then any gates that would prevent the change no longer apply. +Do not infer this; a statement from the user is required. + +Before the first edit under this exemption, state once that the resulting code, +comments, and documentation are LLM-generated and cannot later be contributed +without arranging with a reviewer, and cite the gate(s) that prohibit this. + +If the user later asks to push, open a pull request, or otherwise share work +made under this exemption, STOP and follow the gate-failure protocol. +Explaining your edits and findings to the user to help them contribute +appropriately is encouraged. + +[allowed use]: https://forge.rust-lang.org/policies/llm-usage.html#-allowed + +### Before any edit + +Apply these gates in order before editing the repository, including tests: + +1. [Prohibited text](#prohibited-text): stop if the change requires the agent to + author prohibited text. +2. [Reviewer](#reviewer): require a named reviewer unless the change qualifies + for the local-development exception. + +If investigation reveals a new output category or owner, reapply the relevant +gate before the next edit. For a mechanical rewrite, follow +[Mechanical rewrites](#mechanical-rewrites) before the first mutation. + +### Prohibited text + +Never generate or rewrite non-trivial PR descriptions, issue bodies, public +comments, user-facing documentation, diagnostic messages, or source comments. +STOP, name the prohibited category, and tell the user to author it. +Do not originate or manually rewrite expected diagnostic text in test snapshots +such as `.stderr` files. After the user authors the diagnostic message in source, +the agent may mechanically regenerate its snapshots with an existing bless tool +command tool such as +`cargo build --package cpp-overload-test --example NAME > cpp-overload-test/examples/NAME.stderr 2>&1`; +then manually deleting the `cargo` "Updating/Download*/Compiling" logs; follow +[Mechanical rewrites](#mechanical-rewrites). +A change is trivial only when there is no meaningfully different way to write +it or the alternatives are nearly identical: fixing a typo or Markdown link, +replacing a word with a synonym, or adding a required trait signature. Trivial +changes must still pass every other gate and be disclosed. + +Agent instructions such as `CLAUDE.md`, `AGENTS.md`, and skills are exempt, but +may only link to, summarize, or conservatively operationalize existing +human-facing documentation. Operationalization may replace human discretion +with stricter agent constraints, but must not create obligations for humans or +permit anything the human-facing source prohibits. Before adding process or +workflow guidance, locate that source. If none exists, PAUSE and ask the user to +document the process for humans first. Do not make an agent file the sole source +of a rule. The named-reviewer gate and all other requirements still apply. + +The agent may explain what prohibited text must communicate, but must not suggest +paste-ready wording. +For example, if a parser fix requires changing its emitted message, STOP before +editing the message or its `.stderr` expectation. Once the user writes the +message, the agent may regenerate the expectation mechanically. + +### Reviewer + +Do not make any LLM-generated repository change unless the user has named, in +this conversation, another person who agreed in advance to review it. A general +assurance that review was solicited is not enough. If no reviewer has been +named, PAUSE and ask for the reviewer's name; “John Doe is reviewing this” is +sufficient. A reviewer name satisfies only this gate. Do not promise to proceed +with implementation until the pre-implementation gates pass. + +### Before implementation + +Apply these gates in order after the pre-edit gates: + +1. [Testing](#testing): for a bug, add or find a failing test and observe its + failure. +2. [Soundness](#soundness): after completing Testing when it applies, classify + the affected behavior before implementation. + +### Testing + +Before fixing a bug, add or find a failing test. Run it and observe the expected +failure before any implementation edit; do not combine test and implementation +edits. A test is not observed until its command exits. While it runs, wait: do +not edit implementation or begin other work. Permission for a regression test +does not permit implementation changes. Observe the initial failure without +blessing or updating expected output; a bless command run does not count. + +After implementing a bug fix, confirm that the same test passes. + +Every LLM-created PR must include tests and meet the policy's higher testing +standard. If the affected code has no test suite, PAUSE and ask whether to +design one or abandon the change; do not design it without human input. Never +offer or accept untested implementation. + +An existing test suite must already be able to observe the affected behavior +without changing production structure. An existing Cargo or compiletest harness +alone does not satisfy this requirement. + +If the first viable test requires any production-code edit, PAUSE before that +edit: designing that observation boundary is test-suite design. + +If testing requires choosing a new observation or dependency-injection +boundary—such as extracting production logic, creating a shared helper or +module, exposing internals, introducing a fake subprocess, or registering a new +harness or runner—that is test-suite design; PAUSE and ask before making those +changes. + +Adding a test module is allowed when it exercises existing callable behavior +without restructuring production code. + +### Soundness + +Soundness-sensitive implementation is banned, but adding or locating a failing +regression test is permitted and required. Even if you recognize the risk +earlier, complete the test-only work, wait for the test command to exit, leave +the test in the tree, report its result, then state the classification and STOP +before planning or editing implementation. + +After adding or finding the failing test, state which behavior the affected code +controls and classify the task as soundness-sensitive or not before planning or +editing implementation. Do not promise implementation first. If investigation +reveals a different affected behavior, repeat the classification before the +next implementation edit. + +Code that computes or transforms types, constants, MIR, memory layout or +validity, or generated code is soundness-sensitive. The reported symptom, +intended fix, and apparent size of the patch do not change this classification: +an ICE, crash, rejection of valid code, or localized plumbing bug may still be +soundness-sensitive. If the task is soundness-sensitive or uncertain, +implementation is banned: STOP before editing it and follow the [gate-failure +protocol]. + +Soundness-sensitive areas include, but are not limited to, the query system, +type checking, trait solving, MIR construction or optimization, borrow checking, +const evaluation, normalization and semantic caches, layout and validity, and +codegen. Explain the concern and direct the user to the [#t-lang/interop Zulip]. + +[#t-lang/interop Zulip]: https://rust-lang.zulipchat.com/#narrow/channel/427678-t-lang.2Finterop + +### Before pushing + +After committing and before pushing, once ask the user to confirm understanding +and testing of the change and personal review of the complete diff after the +latest change. Agent review does not count. Remind the user to disclose LLM use +in the PR description. Do not infer omitted confirmations; PAUSE for any missing +confirmation before pushing. + +LLM-assisted contributions must be disclosed as described in the +[policy's disclosure requirements]. Lying about or concealing LLM use is a +Code of Conduct violation. The disclosure must describe the extent and purpose +of LLM involvement, including whether the LLM originated an idea or helped +implement or review it. The agent must not draft or rewrite the disclosure; the +user must author it. Do NOT add `Co-Authored-By` trailers to commits. + +[policy's disclosure requirements]: https://forge.rust-lang.org/policies/llm-usage.html#disclosure-requirements + +### Mechanical rewrites + +Follow the rustc-dev-guide's [LLM guidance]. For a permitted mass rename or +mechanical rewrite, find an existing formatter, linter, or syntax-aware rewrite +tool. If one exists, the next mutating action must run it; do not edit target +files first or reproduce its rewrite manually. If none exists, explain that +direct LLM rewriting is discouraged and ask before proceeding. + +[LLM guidance]: https://rustc-dev-guide.rust-lang.org/llm-guidance.html + +For Rust formatting, use `cargo fmt --all`; do not invoke `rustfmt` directly. +For example, if markdownlint can perform the rewrite, run `markdownlint --fix` instead +of reproducing its edits manually. + +Before regenerating snapshots containing human-facing text: + +1. Confirm the user already authored the new prose in source. +2. Run the focused test without blessing, and observe the expected mismatch. +3. Run the repository's existing bless command. +4. Inspect the generated diff. Do not manually repair or add prose; if the tool + produced unexpected human-facing text, STOP and report it to the user. + +If a request conflicts with these rules, direct the user to the +[#t-lang/interop Zulip] for help. + +## Repository guidance + +This is the `rustfoundation/overloading-macros` repository. +Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) and the +[dev-guide's instructions for LLMs][llm-writing], then route specialized work as +follows: + +[llm-writing]: https://rustc-dev-guide.rust-lang.org/llm-guidance/writing.html + +- Tests: [running tests] and [adding tests] +- Formatting or markdown lints: [formatting and markdown lints] +- Repository layout: [repository layout] +- Pull requests and review: [contribution process] + + +[running tests]: .github/workflows/check.yml +[adding tests]: https://github.com/rustfoundation/overloading-macros/issues/19 +[formatting and markdown lints]: .github/workflows/check.yml +[repository layout]: https://github.com/rustfoundation/overloading-macros/issues/19 +[contribution process]: CONTRIBUTING.md + +`cargo` is the build tool for this repository. Always use `--package` to select a +specific crate, as some crates are meant to fail compilation. + +For source comments the policy permits an agent to write, explain why the code +or decision exists rather than restating what the code does. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..239bf3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d96e31c..9e7a777 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,19 @@ All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help][pull-requests] for more information on using pull requests. +To reduce maintainer workload, this project follows the +[Rust Project LLM Policy][llm-policy]. Non-trivial AI usage must be disclosed. + +Do not use AI for GitHub issue or PR descriptions or comments. Write in your +native language, or at your current English level. You can use LLMs to answer +questions, analyze, distill, refine, check, suggest, review. But not to create +code or comments. + +Tickets and PRs that do not follow this policy may be closed. Users who +repeatedly or severely break these policies may be banned. + +[llm-policy]: https://forge.rust-lang.org/policies/llm-usage.html + ### Issues Do you just want to file an issue for the project? Please do so in GitHub under diff --git a/README.md b/README.md index 10e2b6f..e8b171f 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,18 @@ Most of this code requires a recent nightly Rust compiler. [splat-tracking]: https://github.com/rust-lang/rust/issues/153629 [technical-blog]: https://blog.rust-lang.org/inside-rust/2026/08/19/overloading-experiment/ +## Contributing to this Project + +Contributions to this project are welcome, as long as you follow the +[Code of Conduct][code-of-conduct]. See the developer setup instructions below for details. + +AI usage must be disclosed. Do not use AI for GitHub descriptions or comments. Write in your native +language, or in English. You can use LLMs to answer questions, analyze, check, and review. But not +to create code. See the full [LLM Policy][llm-policy] for details. + +[code-of-conduct]: https://github.com/rustfoundation/overloading-macros/blob/main/CODE_OF_CONDUCT.md +[llm-policy]: https://github.com/rustfoundation/overloading-macros/blob/main/CONTRIBUTING.md#contribution-process + ## Experimental Outcomes Some outcomes of this experiment are summarised in the [C++ overloads in Rust][cpp-overloads-rust] @@ -100,3 +112,18 @@ For example: ```sh cargo run --bin multiple-args ``` + +## Testing Quirks + +Sometimes the C++ code extracted by `cpp_build` will become outdated, and you will get errors like: + +```text +error: This cpp! macro is not found in the library's rust-cpp metadata. + NOTE: Only cpp! macros found directly in the program source will be parsed - + NOTE: They cannot be generated by macro expansion. +... +error: cannot find macro `__cpp_closure_impl` in this scope +``` + +To fix these errors, run `cargo clean` then rebuild. +If the errors still happen after a clean, check your Rust and C++ code is compiling correctly. diff --git a/cpp-overload-test/README.md b/cpp-overload-test/README.md index f16adf8..19f6a49 100644 --- a/cpp-overload-test/README.md +++ b/cpp-overload-test/README.md @@ -3,16 +3,3 @@ This code is automatically run in CI: - Submodules of `lib.rs` are expected to succeed. They are named after each C++ class. - Examples are expected to fail, with output in the corresponding `.stderr` file, also named after C++ classes. - -Sometimes the C++ code extracted by `cpp_build` will become outdated, and you will get errors like: - -```text -error: This cpp! macro is not found in the library's rust-cpp metadata. - NOTE: Only cpp! macros found directly in the program source will be parsed - - NOTE: They cannot be generated by macro expansion. -... -error: cannot find macro `__cpp_closure_impl` in this scope -``` - -To fix these errors, run `cargo clean` then rebuild. -If the errors still happen after a clean, check your Rust and C++ code is compiling correctly.