docs: add comparison with phpseclib/bcmath_compat to README

[nanasess]

Summary

• Add detailed comparison table between phpseclib/bcmath_compat and bcmath-polyfill
• Include migration guide for seamless switching
• Update v0.0.1 release notes with accurate CI/CD information

Changes

• README.md: Added "Key Differences from phpseclib/bcmath_compat" section with:
  • Comprehensive comparison table
  • Simple migration instructions
• Release Notes: Fixed CI/CD comparison to accurately show both projects use GitHub Actions, with PHP 8.4 support being the key difference

Why?

Users need to understand the differences between the two packages and how to migrate. This documentation makes it clear that bcmath-polyfill offers:

• PHP 8.4 function support (bcfloor, bcceil, bcround)
• Bug fixes for PHP 8.2+ deprecations
• Active maintenance
• Extended CI/CD coverage including PHP 8.4

🤖 Generated with Claude Code

[claude]

Claude finished @nanasess's task —— View job

---

PR Review: Documentation Changes

Reviewing the documentation changes for accuracy, clarity, and completeness.

Todo List:

• Read the modified README.md file
• Analyze the comparison table accuracy
• Review migration guide completeness
• Check documentation best practices
• Provide comprehensive review feedback

✅ Overall Assessment

This PR adds valuable documentation that helps users understand the differences between this library and phpseclib/bcmath_compat. The content is well-structured and addresses a clear user need.

🔍 Review Feedback

✅ Strengths

1. Accurate Technical Claims: Verified that PHP 8.4 functions (bcfloor(), bcceil(), bcround()) are properly implemented in /home/runner/work/bcmath-polyfill/bcmath-polyfill/lib/bcmath.php:154-192

2. Comprehensive Testing: The functions have extensive test coverage in /home/runner/work/bcmath-polyfill/bcmath-polyfill/tests/BCMathTest.php:362-781 with both native function comparison and polyfill-only tests

3. CI/CD Claims Verified: Confirmed in /home/runner/work/bcmath-polyfill/bcmath-polyfill/.github/workflows/ci.yml:27 that the project tests PHP 8.1, 8.2, 8.3, and 8.4

4. Clear Migration Path: Simple 2-step process makes switching libraries straightforward

5. Professional Presentation: Well-formatted table and consistent documentation style

💡 Suggestions for Improvement

1. Specificity on Deprecation Fixes (line 95):

   • Consider being more specific about what "PHP 8.2+ deprecations" were fixed
   • Example: "Fixed parameter type warnings" or reference specific issues

2. Migration Considerations (lines 100-111):

   • Could mention checking composer.lock for version conflicts
   • Consider noting that both libraries use the same namespace, making migration seamless

3. Subjective Claims (line 97):

   • "Active maintenance" is subjective - consider using measurable metrics like "Last updated: [date]" or "Regular releases"

4. Test Suite Pollution (line 96):

   • Could benefit from a brief explanation of what this means for users

🛡️ Security & Performance

• ✅ No security concerns with documentation changes
• ✅ No performance impact from README modifications
• ✅ All external links are to legitimate GitHub repositories

📋 Code Quality

• ✅ Markdown formatting is correct and consistent
• ✅ Table structure is properly aligned
• ✅ Code examples are properly formatted
• ✅ No spelling or grammar issues identified

🧪 Test Coverage

Since this is documentation-only:

• ✅ No test changes required
• ✅ Existing tests validate the technical claims made in the comparison

🎯 Recommendation

APPROVED - This PR adds valuable user-facing documentation with verified technical claims. The minor suggestions above are enhancements, not blockers.

The documentation successfully:

• Differentiates this library from the original
• Provides clear migration instructions
• Uses verified technical facts in comparisons
• Maintains professional tone and formatting

---