Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
64 lines (45 loc) · 2.21 KB

CONTRIBUTING.md

File metadata and controls

64 lines (45 loc) · 2.21 KB

Contributing to ghscope

Thanks for wanting to contribute. Here's what you need to know.

Getting started

git clone https://github.com/phlx0/ghscope
cd ghscope
go build .          # produces ./ghscope
go test ./...       # run tests

A GITHUB_TOKEN with public_repo read scope speeds things up a lot — without it you're rate-limited to 60 req/h. Set it in your shell or run ./ghscope setup after building.

Project layout

main.go                     entry point, cobra commands
internal/
  api/          thin GitHub API wrappers, each with disk-cache support
  analysis/     pure computation on top of the API data
  ui/           Bubble Tea model, tab views, setup wizard
  cache/        SHA256-keyed JSON file cache (~/.cache/ghscope)
  config/       ~/.config/ghscope/config.json
  geo/          IP → country resolution for stargazers

The layering matters: api never imports analysis, analysis never imports ui. Keep it that way.

Adding a new analysis tab

  1. Add an API call in internal/api/ — always cache the response with a sensible TTL.
  2. Compute the stat in internal/analysis/ — export the type from types.go, add the module constant to ModuleOrder.
  3. Wire the goroutine in analysis/run.go — call done(ModuleXxx, err) at the end.
  4. Add internal/ui/tab_xxx.go with a renderXxx(s *analysis.RepoSummary, w, h int) string function.
  5. Register the tab name in ui/model.go and add a case "Xxx": in the view switch.

Style

  • No comments except where the why isn't obvious from the code
  • Unexported helpers are fine; don't export something just because it might be useful later
  • Tests live next to the code they test (foo_test.go in the same package)
  • Commit messages: lowercase imperative, no period — add trending signal to overview

Running the demo locally

Install VHS, then:

make demo

This writes demo/demo.gif.

Pull requests

  • Keep PRs focused — one thing at a time
  • If you're adding a new API call, note the approximate call cost in the PR description
  • Existing tests must pass; new analysis code should have at least one test

Questions

Open a discussion or an issue — both work.