docs: overhaul for scripts and their end-to-end tests

[JoshuaKGoldberg]

PR Checklist

• Addresses an existing open issue: fixes 📝 Documentation: Explain how to work with end-to-end migration test snapshots #1141; fixes 🛠 Tooling: Run initialize command (script) in e2e test #1186
• That issue was marked as status: accepting prs
• Steps in CONTRIBUTING.md were taken

Overview

Adds some inline comments to end-to-end tests, as well as a more full description of what to do with migration snapshots in development docs. Also simplifies the migration test error to suggest looking at the docs.

Touches a little bit on what #1045 requests around more clear and standardized token docs.

Co-authored-by: John Reilly [email protected]
Co-authored-by: Mohammad Bagher Abiyat [email protected]

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (0b2d425) 94.61% compared to head (821bbdb) 94.68%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1187      +/-   ##
==========================================
+ Coverage   94.61%   94.68%   +0.07%     
==========================================
  Files          99      102       +3     
  Lines        5666     5685      +19     
  Branches      466      466              
==========================================
+ Hits         5361     5383      +22     
+ Misses        304      301       -3     
  Partials        1        1              

Flag	Coverage Δ
create	70.30% <93.61%> (+0.10%)	⬆️
initialize	42.50% <29.78%> (+0.08%)	⬆️
migrate	69.85% <93.61%> (+0.10%)	⬆️
unit	73.70% <93.61%> (+0.54%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[JoshuaKGoldberg]

Okie dokie, thanks for the suggestions! I'm going to merge this now to get the docs improvements in. If there are more suggestions you'd want to make feel free to file an issue or just send a PR (either or both, whatever's easier for you). These things are tricky 😄

[JoshuaKGoldberg]

@all-contributors please add @gmail.com> for doc.

🤖 Beep boop! This comment was added automatically by all-contributors-auto-action.
Not all contributions can be detected from Git & GitHub alone. Please comment any missing contribution types this bot missed.
...and of course, thank you for contributing! 💙

[allcontributors]

@JoshuaKGoldberg

Could not find the user gmail.com> on github.

[JoshuaKGoldberg]

Hmm. That should have been fixed by JoshuaKGoldberg/all-contributors-for-repository#88 -> JoshuaKGoldberg/all-contributors-for-repository#89.

Filed a new issue: JoshuaKGoldberg/all-contributors-for-repository#199

[github-actions]

🎉 This is included in version v1.52.7 🎉

The release is available on:

• GitHub releases
• npm package (@latest dist-tag)

Cheers! 📦🚀