From 5d6e4b43dbcbf958fcbd4fbfc2ac46259eaa835e Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Tue, 21 Apr 2026 20:53:14 +0700 Subject: [PATCH] docs: note start-of-week in design-guidelines, codebase-summary, deployment-guide - design-guidelines: heatmap row order + productive-weekday bar order now derive from Profile.WeekStart - codebase-summary: list new weekday_start_test.go cases + TestParseWeekday - deployment-guide: mention start_of_week as an optional action input in the workflow template --- docs/codebase-summary.md | 5 +++-- docs/deployment-guide.md | 1 + docs/design-guidelines.md | 4 +++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/codebase-summary.md b/docs/codebase-summary.md index ccaf9dc3..0e6d15b1 100644 --- a/docs/codebase-summary.md +++ b/docs/codebase-summary.md @@ -31,7 +31,7 @@ ghstats/ │ │ ├── productive.go # productive-time (+ all-time) │ │ ├── productive_weekday.go # productive-weekday (+ all-time) │ │ ├── contributions.go # contributions (+ all-time) -│ │ ├── contributions_heatmap.go # contributions-heatmap (7×53 calendar grid) +│ │ ├── contributions_heatmap.go # contributions-heatmap (7×53 calendar grid; row 0 = Profile.WeekStart) │ │ ├── contributions_by_year.go # contributions-by-year bar chart │ │ ├── streak.go # streak (current/longest/active days) │ │ ├── top_starred_repos.go # top-starred-repos bar list @@ -110,8 +110,9 @@ commitHistoryQuery ──► Productive + Weekday + CommitsByLanguage (+ AllTime ## Test coverage - `internal/card/card_test.go` — `RenderAll` produces 15 valid SVGs; XML escape through real render pipeline; `formatInt` cases; `TestDonutSingleSlice` / `TestDonutEmpty` (donut edge cases); `TestCardsFitFrame` (renders every card against an adversarial profile and asserts text + coordinates stay in the 340×200 frame); `TestFitTitleFontSize` (pins the auto-shrink table for every real title); `TestNiceTicksCoversMax` (guards the `yMax ≥ dataMax` invariant so bars can't overflow chartH). +- `internal/card/weekday_start_test.go` — `TestPadToWeekGridRotatesByWeekStart` (leading pad matches configured start day), `TestRenderWeekdayRespectsWeekStart` (bar order rotates with `WeekStart`), `TestRenderHeatmapLabelsRespectWeekStart` (heatmap row labels rotate accordingly). - `internal/github/profile_test.go` — `sortLangStats` ordering and tiebreak. -- `main_test.go` — `TestUTCOffsetLabel` covers UTC, Asia/Saigon, half-hour (Kolkata), quarter-hour (Kathmandu) zones. +- `main_test.go` — `TestUTCOffsetLabel` covers UTC, Asia/Saigon, half-hour (Kolkata), quarter-hour (Kathmandu) zones. `TestParseWeekday` covers the `-start-of-week` input parsing. No network-touching tests; real runs verified via `-token` + local build. diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md index 31fe9824..cc492c98 100644 --- a/docs/deployment-guide.md +++ b/docs/deployment-guide.md @@ -30,6 +30,7 @@ jobs: token: ${{ secrets.GHSTATS_TOKEN }} themes: dracula,github_dark,tokyonight tz: Asia/Saigon + # start_of_week: monday # optional; default sunday — rotates heatmap rows + weekday bars include_forks: "false" include_private: "false" commit_changes: "true" diff --git a/docs/design-guidelines.md b/docs/design-guidelines.md index 211484e3..2be18254 100644 --- a/docs/design-guidelines.md +++ b/docs/design-guidelines.md @@ -72,6 +72,7 @@ When there's **exactly one slice** (one language at 100%), the renderer emits tw | Axis caption | "hour of day" bottom-center on productive-time; weekday / by-year omit the caption since the x labels are self-describing | | Title format | `Commits by Hour (, UTC±H[:MM])` / `Commits by Weekday ()` — weekday drops the UTC so the title always fits at 15 px / `Contributions by Year` | | Hover | `HH:00 — N commits` / `Mon — N commits` / `YYYY — N commits` | +| Bar order | `productive-weekday`: position 0 = `Profile.WeekStart` (set via `-start-of-week`, default Sunday); remaining bars rotate forward `(WeekStart+i) % 7`. Peak highlight tracks the drawn position so it stays aligned with the visible tallest bar. | ## Heatmap card (contributions-heatmap) @@ -81,7 +82,8 @@ When there's **exactly one slice** (one language at 100%), the renderer emits tw | Cell size | 8 × 8 px square, 1 px gap | | Grid geometry | `leftPad 30`, `topPadA 45` (top half), `halfGap 13`, `topPadB 120`. Each half is 7 × 9 − 1 = 62 px tall. Grid bottom at y=182 leaves 18 px for the frame border. | | Cell colour | 5-bucket ramp `mixHex(Background, Accent, k/4)` for `k ∈ 0..4` — no dedicated ramp field on the theme schema | -| Weekday labels | Mon / Wed / Fri only, right-anchored in the `leftPad` gutter | +| Weekday labels | Every other row (positions 1, 3, 5), right-anchored in the `leftPad` gutter. Label text is `weekdayShort[(int(WeekStart)+i) % 7]`, so Sunday-start renders Mon/Wed/Fri; Monday-start renders Tue/Thu/Sat. | +| Row order | Row 0 = `Profile.WeekStart` (`-start-of-week` flag; default `time.Sunday` matches GitHub's own calendar). `padToWeekGrid` rotates the leading blank pad to match. | | Month labels | Printed above the first week where a 1st-of-month day falls; skipped when `x > width − 20` so `Dec` / `Apr` can't spill past the frame | | Legend | "Less ▢▢▢▢▢ More" bottom-right | | Hover | `YYYY-MM-DD — N` per cell |