Document subdirectories of UI tests with README files #141597

Oneirical · 2025-05-26T16:01:24Z

Part of #133895 and the 2025 Google Summer of Code associated project.

When adding a new UI test, one is faced with hundreds of subdirectories in tests/ui reflecting various categories. Knowing where to put the new test is not trivial, as many of the categories have slightly misleading names. For example, moves does not only refer to the move keyword but to functions taking ownership in general, whereas allocator does not refer to allocation in general but rather to the very specific allocator_api and global_allocator features.

Many contributors will therefore place their test at the top level of ̀tests/ui where it will be mixed with hundreds of unrelated tests.

This PR is a tentative move towards more clearly defined tag/categories, with a SUMMARY.md file documenting the true purpose of each subdirectory, placed inside tests/ui.

r? @jieyouxu

jieyouxu · 2025-05-26T16:24:17Z

I feel like this is not super useful unless we explicitly establish an index structure to make those docs discoverable, i.e.

tests/ui/
	SUMMARY.md or README.md <- "index" of directories
    attributes/README.md <- only if there's more subdir specific info to add
    attributes/README.md
        path/README.md <- only if there's even more specific notes

and the in r-d-g, describe this convention, and point to entry point tests/ui/SUMMARY.md.

Oneirical · 2025-05-26T16:29:12Z

That is true. Anyone who doesn't want to comb through the directories certainly isn't going to comb through the READMEs. A single one, where specific strings can be searched, is much superior.

jieyouxu · 2025-05-26T16:44:44Z

I know I've been confused on what ui subdirectories we have, so an TL;DR of exisiting ui dirs, e.g. tests/ui/SUMMARY.md is probably sufficient for vast majority of those subdirs. Sth like

# UI test suite

## Subdirectories

- [`foo/`](./foo/): exercises `foo` area of language

tests/ui/SUMMARY.md

jieyouxu · 2025-05-28T14:11:09Z

@rustbot note pr-description-is-outdated

Can you also update PR description, since we don't anymore have specific per-subdir .mds (no need currently).

jieyouxu · 2025-05-28T14:15:26Z

@rustbot note stub-out-remaining-subdirs

Can you also stub out existing remaining subdirs? E.g.

## `tests/ui/subdir/`: TODO(#141695)

TODO(#141695): add some description

jieyouxu · 2025-06-03T01:32:19Z

@rustbot note remove pr-description-is-outdated

jieyouxu · 2025-06-03T01:32:42Z

@rustbot note remove stub-out-remaining-subdirs

jieyouxu · 2025-06-21T06:45:50Z

@Oneirical thanks for working on this, I find it very helpful. I pushed some edits to your branch, let me know if this version broadly looks good. This is a survey of existing organization of the ui test suite, and does not have to be perfect at all.

If it looks reasonable to you, feel free to r=Oneirical,jieyouxu.

@bors delegate+ rollup

bors · 2025-06-21T06:45:53Z

✌️ @Oneirical, you can now approve this pull request!

If @jieyouxu told you to "r=me" after making some further change, please make that change, then do @bors r=@jieyouxu

jieyouxu · 2025-06-21T06:46:06Z

@rustbot author

rustbot · 2025-06-21T06:46:11Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

jieyouxu · 2025-06-21T07:07:38Z

Actually, could you also leave a one-liner mention about this SUMMARY.md survey in rustc-dev-guide in this PR, i.e. in https://rustc-dev-guide.rust-lang.org/tests/ui.html#introduction to make it more discoverable

Co-authored-by: Jieyou Xu <[email protected]>

rustbot · 2025-06-22T16:18:46Z

The rustc-dev-guide subtree was changed. If this PR only touches the dev guide consider submitting a PR directly to rust-lang/rustc-dev-guide otherwise thank you for updating the dev guide with your changes.

cc @BoxyUwU, @jieyouxu, @Kobzol

Oneirical · 2025-06-22T16:21:20Z

@bors r=Oneirical,jieyouxu

Added the one-liner to the dev guide, and fixed some formatting errors related to `` instead of `.

bors · 2025-06-22T16:21:22Z

📌 Commit b433aba has been approved by Oneirical,jieyouxu

It is now in the queue for this repository.

fmease · 2025-06-22T17:11:59Z

r stands for reviewer ;)

@bors r=jieyouxu

bors · 2025-06-22T17:12:02Z

💡 This pull request was already approved, no need to approve it again.

There's another pull request that is currently being tested, blocking this pull request: Make lowering incremental, take 3/N #142830

bors · 2025-06-22T17:12:03Z

📌 Commit b433aba has been approved by jieyouxu

It is now in the queue for this repository.

…on, r=jieyouxu Document subdirectories of UI tests with README files Part of rust-lang#133895 and the [2025 Google Summer of Code](https://blog.rust-lang.org/2025/05/08/gsoc-2025-selected-projects/) associated project. When adding a new UI test, one is faced with hundreds of subdirectories in `tests/ui` reflecting various categories. Knowing where to put the new test is not trivial, as many of the categories have slightly misleading names. For example, `moves` does not only refer to the `move` keyword but to functions taking ownership in general, whereas `allocator` does not refer to allocation in general but rather to the very specific `allocator_api` and `global_allocator` features. Many contributors will therefore place their test at the top level of ̀`tests/ui` where it will be mixed with hundreds of unrelated tests. This PR is a tentative move towards more clearly defined tag/categories, with a SUMMARY.md file documenting the true purpose of each subdirectory, placed inside `tests/ui`. r? `@jieyouxu`

Rollup of 6 pull requests Successful merges: - #140136 (Add an aarch64-msvc build running on ARM64 Windows) - #141597 (Document subdirectories of UI tests with README files) - #142823 (Port `#[no_mangle]` to new attribute parsing infrastructure) - #142828 (1.88.0 release notes) - #142854 (centralize `-Zmin-function-alignment` logic) - #142875 (Check rustdoc-json-types FORMAT_VERSION is correctly updated) r? `@ghost` `@rustbot` modify labels: rollup

tshepang · 2025-06-23T05:34:33Z

a file like this is normally README.md... seeing SUMMARY made be think this was a new mdbook tree

Rollup of 5 pull requests Successful merges: - #141597 (Document subdirectories of UI tests with README files) - #142823 (Port `#[no_mangle]` to new attribute parsing infrastructure) - #142828 (1.88.0 release notes) - #142854 (centralize `-Zmin-function-alignment` logic) - #142875 (Check rustdoc-json-types FORMAT_VERSION is correctly updated) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #141597 - Oneirical:unquestionable-instruction, r=jieyouxu Document subdirectories of UI tests with README files Part of #133895 and the [2025 Google Summer of Code](https://blog.rust-lang.org/2025/05/08/gsoc-2025-selected-projects/) associated project. When adding a new UI test, one is faced with hundreds of subdirectories in `tests/ui` reflecting various categories. Knowing where to put the new test is not trivial, as many of the categories have slightly misleading names. For example, `moves` does not only refer to the `move` keyword but to functions taking ownership in general, whereas `allocator` does not refer to allocation in general but rather to the very specific `allocator_api` and `global_allocator` features. Many contributors will therefore place their test at the top level of ̀`tests/ui` where it will be mixed with hundreds of unrelated tests. This PR is a tentative move towards more clearly defined tag/categories, with a SUMMARY.md file documenting the true purpose of each subdirectory, placed inside `tests/ui`. r? ``@jieyouxu``

rustbot assigned jieyouxu May 26, 2025

rustbot added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label May 26, 2025