rust-lang / rust-lang/rust

Document the `run_make_support` library

Open
#126,645 0 comments 0 reactions 1 assignee View on GitHub

@jieyouxu is already working on this.

Since Jun 18, 2024.

A-contributor-roadblock A-docs A-run-make T-compiler
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

The support library has some sparse doc comments via ./x doc src/tools/run-make-support, but it really needs some better high-level docs to help test writers (otherwise the support library is very hard to discover). There also needs to be crosslinks from rustc-dev-guide back to these docs.


https://rust-lang.zulipchat.com/#narrow/stream/421156-gsoc/topic/Project.3A.20Rewriting.20Makefile.20Tests.20Using.20Rust/near/443513926 reproduced here for convenience:

I'm thinking that I should add some docs for the support library, for stuff like:

  • Assumptions (e.g. paths relative to the working directory of the test being run)
  • Key API design: the Command wrapper and CompletedProcess etc.
  • Synposis of common Command and CompletedProcess APIs
  • Guidance for adding new command wrappers, adding new dependencies, when to uplift things from tests to the support library etc.
  • Recommendations: error reporting
  • Reminder to augment and update the changelog

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.