The old automation was entirely dead: .travis.yml ran awesome_bot on Travis OSS (shut down), and .github/stale.yml targeted a defunct probot integration. Result: dozens of dead links, years-old broken-link issues, and duplicate PRs fixing the same link. Adds scripts/check_readme.py, a stdlib-only Python validator that parses README.md as structured data (grammar shared by every subcommand so lint/PR checks/the weekly sweep can't drift apart): - `lint`: whole-file grammar, duplicate-URL, and Table of Contents checks - `check-diff`: flags only PR-added lines (shorteners, new http://, malformed entries) so pre-existing link rot can't fail unrelated PRs - `check-links`: liveness-checks URLs with a 2-strike state machine, treating bot-hostile domains (Medium, Reddit, etc.) as BLOCKED rather than dead - `report`: renders the weekly link-rot issue body Wires this up via three workflows: validate-pr.yml (fork-safe PR gate), link-rot.yml (weekly sweep, maintains one consolidated issue instead of scattered reports), and stale-prs.yml (PRs only -- issues are explicitly exempted, unlike the old probot config that buried broken-link reports). Also replaces the generic issue/PR templates with ones that match what the validator actually enforces, and fixes CONTRIBUTING.md's `*`-bullet examples (the real source of format drift) to `-`.
1.8 KiB
1.8 KiB
Contribution guidelines
Before making a pull request, please make sure of the following:
- The tutorial(s) you want to add do not already exist (search README.md for the URL and the title).
- Your tutorial is correctly placed under the appropriate language/technology section.
- The tutorial is free and open -- no paywall, login wall, or required newsletter signup.
- The tutorial is project-based -- following it, the reader builds a complete, working artifact (not just a concept explainer).
- If you're the author of the tutorial, or affiliated with the author or site, say so in the pull request.
- The pull request needs to have a descriptive title.
- If the language/technology of your tutorial does not exist, feel free to create a new entry in the table of contents.
- Make a separate pull request for each of the tutorials.
- Use the following format:
- [Title](link_to_tutorial). - If your tutorial is a multi-part series, use the following format:
- Title - [Part 1](link_to_part_1) - [Part 2](link_to_part_2) - Check the spelling and grammar.
- Remove any trailing whitespace.
- Links must point straight to the tutorial -- no URL shorteners.
Before opening the pull request, run the validator locally from the repo root:
python3 scripts/check_readme.py lint
It must exit with status 0. It checks the grammar above, the Table of Contents, and for duplicate/shortened URLs.
CI also checks that any link you add is reachable. Some sites (Medium, Reddit, LinkedIn, Udemy, and similar) block automated checks and will show up as "could not verify" rather than failing the build -- that's expected, not something to fix.
Thank you for your suggestions! If you think there is anything to improve with the guidelines, please contact me at tuvtran97@gmail.com