Add comprehensive documentation and CLI enhancements for custom MicroPython builds with full test coverage

[Copilot]

This PR enhances the micropython-stubber to support custom MicroPython builds with arbitrary git references (tags, branches, commits) and provides comprehensive documentation for the new functionality.

Key Features

Enhanced CLI Commands

• Flexible git reference support: The stubber switch and stubber clone commands now accept any valid git reference:
  • Version tags: stubber switch v1.22.0
  • Branch names: stubber switch main
  • Commit hashes: stubber switch abc1234
  • Special references: stubber switch stable (resolves to latest stable version)

Robust Fallback Mechanism

The implementation includes intelligent fallback logic that tries git references in order:

1. First as a tag (git switch-tag)
2. Then as a branch (git switch-branch)
3. Finally as a commit hash (git checkout-commit)
4. Clear error reporting if none succeed

Comprehensive Documentation

• New guide: docs/25_custom_micropython.md covering custom MicroPython builds
• Enhanced existing docs: Updated quick start and creation guides with new examples
• Cross-references: Integrated the new documentation throughout existing files

Example Usage

# Use latest stable version (recommended)
stubber switch stable

# Switch to a specific version
stubber switch v1.23.0

# Work with development branches
stubber switch main

# Clone custom repositories
stubber clone --url https://github.com/myorg/custom-micropython.git --version feature-branch

Quality Assurance

• Full test coverage: Added comprehensive tests covering all new code paths and error conditions
• Backward compatibility: All existing functionality remains unchanged
• Future-proof examples: Documentation uses stable instead of hardcoded versions

This enhancement enables developers to create stubs for custom MicroPython variants, development branches, and specific commits while maintaining the reliability and ease of use of the existing tooling.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.58%. Comparing base (8c44434) to head (6e83889).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #682      +/-   ##
==========================================
+ Coverage   78.05%   78.58%   +0.52%     
==========================================
  Files          70       70              
  Lines        6453     6466      +13     
  Branches     1079     1079              
==========================================
+ Hits         5037     5081      +44     
+ Misses       1054     1034      -20     
+ Partials      362      351      -11     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Josverl]

@copilot , please increase test coverage of the new code.

 in your changes missing coverage. Please review.
✅ Project coverage is 78.00%. Comparing base (a5ee49a) to head (cf973d5).
⚠️ Report is 4 commits behind head on main.

Files with missing linesPatch %Linessrc/stubber/utils/repos.py35.71%9 Missing ⚠️

❌ Your patch check has failed because the patch coverage (50.00%) is below the target coverage (80.00%). You

[Copilot]

@copilot , please increase test coverage of the new code.

 in your changes missing coverage. Please review....

I've added comprehensive test coverage for the missing lines in src/stubber/utils/repos.py. The new tests specifically target the enhanced functionality added for custom MicroPython builds, covering:

• All fallback paths in fetch_repos (tag → branch → commit)
• Error handling for invalid git references
• Preview tag and stable tag handling
• Missing error conditions in other functions

The tests use proper mocking to avoid external dependencies and focus on the 9 missing lines identified in the coverage report. (2598871)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/micropython/micropython
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/pytest tests/utils/repos_test.py -v --cov=src/stubber/utils/repos --cov-report=term-missing (http block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python -m pytest tests/utils/repos_test.py::TestFetchRepos::test_fetch_repos_valid_tag -v (http block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python -m pytest tests/utils/test_repos_enhanced.py::TestFetchRepos::test_fetch_repos_valid_tag -v -s (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)