Possible Enhancements

[thorwhalen]

To jot down ideas of enhancements

[thorwhalen]

Shields.io (Badges)

A few Q&As...

1. Does Shields.io track and record history?

No. Shields.io is purely a "now" service. It fetches the current state of a URL (or API), turns it into an image, and forgets it immediately. It does not have a database, it does not "scan" your code, and it does not keep a history of your quality over time.

How to solve this (The "Recorder" Solution):
To track the progress of quality (e.g., "Did my code coverage drop since last week?"), you need an Analytics Service or a Custom CI Job.

• Use Dedicated Services: Tools like Codecov, Coveralls, or SonarCloud are designed exactly for this. They integrate with your CI (GitHub Actions), record the data for every commit, keep the history, and then provide an API that Shields.io reads to make the badge.
• Do It Yourself (DIY): You can write a GitHub Action that runs your tests, extracts the numbers (coverage, complexity), appends them to a CSV/JSON file in your repo (or an external database), and commits that file. This gives you a permanent record.

2. Can I control badge visibility dynamically?

Yes, but you have to build the logic yourself.
Since README.md is just a static text file, it doesn't have "if/else" logic. To achieve "If coverage < 80%, hide badge," you need a CI/CD Script.

The Workflow:

1. Run Tests: Your GitHub Action runs your test suite.
2. Check Thresholds: A script (Python/Bash) checks the output.
   • Example: if coverage_score < 80: show_badge = False
3. Rewrite README: The script opens your README.md, looks for the specific line containing the badge, and either deletes it or adds it back in.
4. Commit: The Action commits the modified README.md back to the repo.

Note: There are tools like readme-scribe or markscribe that help template this process so you don't have to use regex.

---

3. The "Maximal" Set (For your internal auditing)

If you want to gather every possible metric to gauge the "health" of a project (even if you don't show them all), here is what Shields.io can visualize if you have the underlying tools running:

• Code Quality & Debt:
  • Technical Debt Ratio: (via SonarQube) - How long to fix the code.
  • Cognitive Complexity: (via CodeFactor) - How hard is the logic to read?
  • Maintainability Rating: (A–F grades).
• Security:
  • Vulnerabilities: (via Snyk or Dependabot) - Number of known security holes.
  • Security Grade: (via LGTM or similar).
• Activity/Churn:
  • Commit Activity: (via GitHub) - Is the project alive?
  • Last Commit Date: - Has it been abandoned?
  • Pull Requests: Open vs. Closed.
• Testing:
  • Branch Coverage: (via Codecov) - Are all if/else paths tested?
  • Line Coverage: Total lines hit by tests.
• Package Health:
  • Wheel Size: (via PyPI) - Is the download huge?
  • Dependency Count: How many external libraries does this rely on?

---

4. The Standard Badge Sets

When showing badges to the public, "less is more." You want to signal trust without clutter.

A. Minimal Set (The "Is this dead?" Check)

Use this for small utilities or scripts.

1. Build Status: (Pass/Fail) - Does the code actually run?
2. Package Version: (PyPI/NPM) - Tells users it is installable.
3. License: (MIT/Apache) - Tells users if they are legally allowed to use it.

B. Medium Set (The "Is this professional?" Check)

Use this for libraries you want others to depend on.

1. All of the Minimal Set.
2. Code Coverage: (e.g., "Coverage: 92%") - Shows you care about testing.
3. Downloads/Month: (Social Proof) - Shows others are using it.
4. Supported Versions: (e.g., "Python 3.9 | 3.10 | 3.11") - Vital for compatibility.
5. Code Style: (e.g., "Black" or "Prettier") - Shows the code is formatted cleanly.

Summary Table for Your Strategy

Requirement	Tool	Strategy
Generate Badges	Shields.io	Use for the visual image only.
Record History	Codecov / SonarCloud	Connect these to your repo to store the data over time.
Dynamic Logic	Python script in GitHub Actions	Write a script to read the data from step 2, and edit the README.md text to add/remove badges based on your rules.

Would you like me to write a simple Python script example that updates a README based on a "coverage" number?