docs: top-level documentation review and AI policy#470
Merged
Conversation
Thorough review of all top-level .md files for clarity, consistency, and utility. Changes include: High priority: - Remove stale feature/defer-blocks regression tracking from AGENTS.md - Reconcile `make` command descriptions across all files - Extend `make check-links` to cover top-level .md files - Fix contradictory "Make optional" in QUICKSTART.md Medium priority: - Clarify "Perl 5.42+ features" -> "Perl 5.42 language compatibility" - Align CONTRIBUTING commit/PR workflow with AGENTS.md rules - Add project independence note to README - Link AGENTS.md from CONTRIBUTING.md Low priority: - Add SECURITY.md to README About line - Note AI_POLICY stats are point-in-time with regeneration command - Improve LICENSE.md link text clarity - Add value proposition for non-Perl users in README - Simplify README license line - Add JVM update recommendation to SECURITY.md - Rename "Open Questions" to "Future Considerations" in AI_POLICY.md New files: - AI_POLICY.md: AI-assisted development policy and industry research - SECURITY.md: Added Perl 5 independence section, AI code review note - dev/design/docs.md: Documentation improvement plan with full findings - .gitignore: Allow SECURITY.md and AI_POLICY.md All 205 local links verified via lychee. Build passes. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
The previous commit accidentally removed the links to the Artistic and Copying license files in the README license line. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Thorough review of all top-level
.mdfiles for clarity, consistency, and utility for first-time and advanced users. Also adds a new AI-assisted development policy document based on research into how major open-source projects handle AI contributions.New files
High priority fixes
feature/defer-blocksregression tracking from AGENTS.mdmakecommand descriptions across README, QUICKSTART, CONTRIBUTING, AGENTS.mdmake check-linksto cover top-level.mdfiles (was only checkingdocs/anddev/design/)Medium priority fixes
makevsmake test-all)Low priority fixes
SECURITY.md improvements
.gitignore
SECURITY.mdandAI_POLICY.md(were blocked by/*.mdpattern)Test plan
make check-links— 205/205 local links pass, 0 errorsmake— BUILD SUCCESSFUL (all unit tests pass)check-linkstarget and .gitignore)Generated with Devin