Skip to content

Improve GitHub discovery and contributor onboarding #573

Description

@jimmykane

Goal

Make Quantified Self easier to find through GitHub search and easier for new users and contributors to understand, evaluate, and engage with.

Current state

  • Baseline: 221 stars and 30 forks when this work was scoped.
  • Repository topics include dated campaign tags: hacktoberfest, hacktoberfest2020, and hacktoberfest2021.
  • The README explains the product but does not show its main workflows visually.
  • The repository does not have structured issue forms.
  • GitHub Discussions is disabled.
  • The canonical good first issue label is missing.

Scope

1. Refresh repository topics

Remove the dated Hacktoberfest topics while preserving relevant existing topics. Add:

  • garmin
  • suunto
  • coros
  • wahoo
  • fit-file
  • training-analysis
  • fitness-data
  • mcp
  • sports-analytics

2. Add a README product tour

Add a lightweight animated GIF near the top of the README that communicates:

  • Garmin, Suunto, COROS, and Wahoo connections
  • FIT/GPX/TCX and other file imports
  • training analysis and trends
  • device comparison
  • the grounded Assistant/MCP workflow
  • privacy and data portability

The image must have useful alt text, link to the hosted app, render correctly on GitHub, and remain reasonably small.

3. Add issue forms

Add structured forms for:

  • reproducible bug reports
  • feature requests framed around the user problem
  • provider/device integration requests

Disable unstructured blank issues and route usage questions to Discussions and security reports to the private security channel. All public forms should warn users not to attach credentials, private activity files, personal health data, or precise locations.

4. Improve community entry points

  • Enable GitHub Discussions.
  • Create the good first issue label with a clear newcomer-oriented description.
  • Link the README to Discussions and the good first issue label.

Implementation checklist

  • Merge draft PR docs: improve GitHub discovery #572 for the issue forms and contributor links.
  • Supply or approve a real product screen recording for the README GIF; the rejected mock-up has been removed.
  • Remove hacktoberfest, hacktoberfest2020, and hacktoberfest2021 from repository topics.
  • Add all nine discovery topics listed above.
  • Enable GitHub Discussions.
  • Create the good first issue label.
  • Curate at least 3 bounded, documented issues suitable for the new label.
  • Verify README image and links on the rendered repository page.
  • Verify all issue forms appear in the new-issue chooser.
  • Verify the Discussions contact link opens the repository's Discussions area.

Acceptance criteria

  • None of the dated Hacktoberfest topics remain.
  • Every requested discovery topic is visible on the repository profile.
  • The README product GIF loads and clearly introduces the main product workflows.
  • Bug, feature, and provider/device request forms submit successfully.
  • Questions are directed to an enabled Discussions area.
  • The good first issue label exists and can be applied to newcomer-ready work.
  • No application behavior, production infrastructure, or user data handling is changed by this enhancement.

Validation

For the current repository-content portion in PR #572:

  • issue-form YAML parses successfully
  • the rejected mock-up and its README reference are absent from the final diff
  • the branch changes only the four issue-form files and README contributor links
  • no application tests are required because the change is documentation and GitHub configuration only

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions