Document the `run_make_support` library
Open
@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
Commandwrapper andCompletedProcessetc. - Synposis of common
CommandandCompletedProcessAPIs - 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.