[Merged by Bors] - CI - Check that examples are listed in README and Cargo #1650

Weibye · 2021-03-14T08:19:52Z

Internal File/Link Consistency checker Action

This pull request adds an action to the CI that parses the ./examples folder for files and cross references that with the links listed in README.md and Cargo.toml to ensure the documentation actually reflects the examples currently in the repo.

The primary reason for why we want this, is to prevent people from adding new examples but forgetting to also list them in the docs, or accidentally entering broken links (typos in docs).

For details on how the action is working: Check out the README here

Weibye · 2021-03-27T21:36:05Z

@alice-i-cecile @mockersf @MinerSebas
Continuing conversation from #1650 over here:

This is a screenshot of the action currently in use on this pull request: https://github.com/bevyengine/bevy/pull/1650/checks?check_run_id=2209782326

I am mostly happy with the results but I'm currently trying to improve the clarity and directness of the output so that users immediately know what corrections need to take place.

In this case the action has picked up 3 issues, which on closer inspection is really 2 distinct problems:

./examples/3d/pbr.rs is currently missing from README and must be added
./examples/3d/pbr_textures.rs is missing from both README and Cargo and should be added to both targets.
./examples/3d/[pbr].rs is found in README, but there has not been found an accompanying file on disk.

Now, 1 and 3 is the same issue: There is a typo in the README (brackets should not be there).

Do you all have any insight into how I can improve the outputs given?
Since this is potentially going to affect quite a few people, I want this to be as helpful and direct as possible and not cause unnecessary friction.

Edit: Is there any legitimate reason for the link ./examples/3d/[pbr].rs to have brackets in them in a Markdown document?

Weibye · 2021-04-09T19:46:46Z

Think I really messed up my git rebasing, will try to fix

Weibye · 2021-04-09T20:15:06Z

I'll nuke this one and create a fresh pull request once I'm confident the action does not pick up false-positives

cart · 2021-05-06T02:47:34Z

Just fixed the git history by squashing the commits, rebasing on main, and force pushing.

Weibye · 2021-05-28T07:26:39Z

Sorry for the delay everyone, this is almost complete. Will aim to have the pull request finished by the end of the day today.

Weibye · 2021-05-28T08:06:59Z

I had the action working properly, then #1714 came along and I realized I needed to support examples that does not lie within the examples folder, which has been some of the reason for this delay

Weibye · 2021-05-28T19:44:22Z

I think this is ready now and should be ready to go as #2263 gets merged.

mockersf · 2021-05-28T21:17:43Z

bors try

so it should fail now right?

bors · 2021-05-28T21:35:57Z

try

Build succeeded:

mockersf · 2021-05-28T21:42:04Z

It works, it fails! https://github.com/bevyengine/bevy/runs/2697857713

Could you add it to bors? https://github.com/bevyengine/bevy/blob/main/.github/bors.toml

MinerSebas · 2021-05-28T21:48:55Z

Shouldn't this also currently Fail on the Tests category, as it isn't stored in the examples Folder? (See the ../)

## Tests

Example | File | Description
--- | --- | ---
`how_to_test_systems` | [`../tests/how_to_test_systems.rs`](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources

But the CI config only sets this: source: './examples/'

Weibye · 2021-05-28T22:55:41Z

Shouldn't this also currently Fail on the Tests category, as it isn't stored in the examples Folder? (See the ../)
## Tests

Example | File | Description
--- | --- | ---
`how_to_test_systems` | [`../tests/how_to_test_systems.rs`](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources
But the CI config only sets this: source: './examples/'

Hmm. Yes you are right. I'll fix this in the morning.

What is the desired approach here? Should we force test examples inside the examples folder? Or are test examples another thing that should be ignored?

Weibye · 2021-05-29T09:46:16Z

@mockersf Are there any specific reason why the examples on how to test systems (#1714) should live in the Test folder instead of the Examples folder?

Weibye · 2021-05-29T12:37:44Z

The action should now work and correctly fail on account of Test examples are not located within the scope of examples/
iter_combinations should no longer be picked up as iter_combinations example missing from README #2263 has been merged
I also improved the output messages a bit to hopefully add some clarity

Could you add it to bors? https://github.com/bevyengine/bevy/blob/main/.github/bors.toml

I've also added the action to bors

bors · 2021-05-29T13:44:02Z

try

Build failed:

example-doc-validation

Weibye · 2021-05-29T13:56:27Z

Build failed:
example-doc-validation

Should anyone have a suggestion for a better / clearer name, I'm all ears

mockersf · 2021-05-29T21:50:46Z

@mockersf Are there any specific reason why the examples on how to test systems (#1714) should live in the Test folder instead of the Examples folder?

To be executed when running cargo test

Weibye · 2021-05-30T08:22:43Z

@mockersf Are there any specific reason why the examples on how to test systems (#1714) should live in the Test folder instead of the Examples folder?

To be executed when running cargo test

That makes sense, in which case I propose #2281 in order to unblock this PR

mockersf · 2021-05-30T09:57:19Z

I didn't check how your action works, but if it fails on that it may means it does things backwards: The goal of this PR is to check that examples are in the README.md, not that the examples listed in this file are present in the examples folder.
The fact that those links are valid should already be checked by our link checker in CI

Weibye · 2021-05-30T12:59:45Z

I didn't check how your action works, but if it fails on that it may means it does things backwards: The goal of this PR is to check that examples are in the README.md, not that the examples listed in this file are present in the examples folder.

Currently it does both.

The fact that those links are valid should already be checked by our link checker in CI

The link-checker CI didn't exist at the time I started this work, so I reckoned checking for invalid links would be required to properly solve the problem. I'll remove that check from the action as it is redundant now.

This action will then only check that files within ./examples are present in ./examples/README.md and Cargo.toml, and not the other way around.

bors · 2021-05-30T14:15:31Z

🔒 Permission denied

Existing reviewers: click here to make Weibye a reviewer

Weibye · 2021-05-30T14:21:38Z

I think this should now be complete and work properly this time.

Renamed the action, hopefully to be more clear.
Re-versioned the action to get rid of the old non-working builds

This action should now run without picking up any issues and be ready to merge.

NathanSWard · 2021-05-30T16:36:46Z

bors try

bors · 2021-05-30T16:54:13Z

try

Build succeeded:

cart · 2021-05-30T18:14:43Z

bors r+

cart · 2021-05-30T18:14:58Z

Great work! I feel so safe now :)

Closes #1581 # Internal File/Link Consistency checker Action This pull request adds an action to the CI that parses the [`./examples`](https://github.com/bevyengine/bevy/tree/main/examples) folder for files and cross references that with the links listed in [`README.md`](https://github.com/bevyengine/bevy/blob/main/examples/README.md) and [`Cargo.toml`](https://github.com/bevyengine/bevy/blob/main/Cargo.toml) to ensure the documentation actually reflects the examples currently in the repo. The primary reason for why we want this, is to prevent people from adding new examples but forgetting to also list them in the docs, or accidentally entering broken links (typos in docs). For details on how the action is working: [Check out the README here](https://github.com/Weibye/action-internal-link-consistency/blob/main/README.md) Co-authored-by: Andreas Weibye <[email protected]>

bors · 2021-05-30T18:39:25Z

Pull request successfully merged into main.

Build succeeded:

DJMcNab · 2021-07-16T20:00:48Z

@Weibye please respond in #2373 for the relicense to MIT/Apache 2.0. Thanks!

Weibye · 2021-07-16T20:04:21Z

@Weibye please respond in #2373 for the relicense to MIT/Apache 2.0. Thanks!

Oof, thought I already had. Thanks for the reminder!

DJMcNab · 2021-07-16T20:06:15Z

Yay! Thanks! We missed you in the initial checks for users, but we're doing additional checks and found this PR from that.

) Closes bevyengine#1581 # Internal File/Link Consistency checker Action This pull request adds an action to the CI that parses the [`./examples`](https://github.com/bevyengine/bevy/tree/main/examples) folder for files and cross references that with the links listed in [`README.md`](https://github.com/bevyengine/bevy/blob/main/examples/README.md) and [`Cargo.toml`](https://github.com/bevyengine/bevy/blob/main/Cargo.toml) to ensure the documentation actually reflects the examples currently in the repo. The primary reason for why we want this, is to prevent people from adding new examples but forgetting to also list them in the docs, or accidentally entering broken links (typos in docs). For details on how the action is working: [Check out the README here](https://github.com/Weibye/action-internal-link-consistency/blob/main/README.md) Co-authored-by: Andreas Weibye <[email protected]>

Ratysz added the A-Build-System Related to build systems or continuous integration label Mar 14, 2021

alice-i-cecile mentioned this pull request May 28, 2021

iter_combinations example missing from README #2263

Closed

Weibye marked this pull request as ready for review May 28, 2021 19:44

alice-i-cecile approved these changes May 28, 2021

View reviewed changes

bors bot added a commit that referenced this pull request May 28, 2021

Try #1650:

0464b5a

Weibye marked this pull request as draft May 29, 2021 09:38

This was referenced May 29, 2021

Support multiple sources Weibye/action-internal-link-consistency#77

Open

Detect and fail on misplaced files Weibye/action-internal-link-consistency#78

Closed

Weibye marked this pull request as ready for review May 29, 2021 12:33

Weibye-Breach and others added 7 commits May 29, 2021 14:37

Fixing inconsistencies

377a105

Adding example checker action to repo

592e97d

Fixing typo

73386f6

Minor cleanup

071a38b

Updating action version

ddb1750

Added to bors

a10566d

Using fixed version of action

d2c0a42

Weibye mentioned this pull request May 30, 2021

Separate bevy tests from the example on how to run tests #2281

Closed

Weibye marked this pull request as draft May 30, 2021 13:22

Weibye added 2 commits May 30, 2021 15:58

Renaming action

e5eeafd

Adjusting to new action versioning

794f078

Weibye marked this pull request as ready for review May 30, 2021 14:16

bors bot added a commit that referenced this pull request May 30, 2021

Try #1650:

b26468a

NathanSWard approved these changes May 30, 2021

View reviewed changes

alice-i-cecile approved these changes May 30, 2021

View reviewed changes

alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label May 30, 2021

bors bot changed the title ~~CI - Check that examples are listed in README and Cargo~~ [Merged by Bors] - CI - Check that examples are listed in README and Cargo May 30, 2021

bors bot closed this May 30, 2021

Weibye deleted the ci_examples_improvements branch May 31, 2021 18:19

Uh oh!

[Merged by Bors] - CI - Check that examples are listed in README and Cargo #1650

[Merged by Bors] - CI - Check that examples are listed in README and Cargo #1650

Uh oh!

Conversation

Weibye commented Mar 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Internal File/Link Consistency checker Action

Uh oh!

Weibye commented Mar 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Weibye commented Apr 9, 2021

Uh oh!

Weibye commented Apr 9, 2021

Uh oh!

cart commented May 6, 2021

Uh oh!

Weibye commented May 28, 2021

Uh oh!

Weibye commented May 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Weibye commented May 28, 2021

Uh oh!

mockersf commented May 28, 2021

Uh oh!

bors bot commented May 28, 2021

try

Uh oh!

mockersf commented May 28, 2021

Uh oh!

MinerSebas commented May 28, 2021

Uh oh!

Weibye commented May 28, 2021

Uh oh!

Weibye commented May 29, 2021

Uh oh!

Weibye commented May 29, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bors bot commented May 29, 2021

try

Uh oh!

Weibye commented May 29, 2021

Uh oh!

mockersf commented May 29, 2021

Uh oh!

Weibye commented May 30, 2021

Uh oh!

mockersf commented May 30, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Weibye commented May 30, 2021

Uh oh!

bors bot commented May 30, 2021

Uh oh!

Weibye commented May 30, 2021

Uh oh!

NathanSWard commented May 30, 2021

Uh oh!

bors bot commented May 30, 2021

try

Uh oh!

cart commented May 30, 2021

Uh oh!

cart commented May 30, 2021

Uh oh!

bors bot commented May 30, 2021

Uh oh!

DJMcNab commented Jul 16, 2021

Uh oh!

Weibye commented Jul 16, 2021

Uh oh!

DJMcNab commented Jul 16, 2021

Uh oh!

Uh oh!

Weibye commented Mar 14, 2021 •

edited

Loading

Weibye commented Mar 27, 2021 •

edited

Loading

Weibye commented May 28, 2021 •

edited

Loading

Weibye commented May 29, 2021 •

edited

Loading

mockersf commented May 30, 2021 •

edited

Loading