Skip to content

Commit 8178782

Browse files
JhaSourav07JhaSourav07
authored
docs(readme): document ?grace= URL parameter in README parameter table (JhaSourav07#1719)
## What does this PR do? Documents the `?grace=` URL parameter in the README parameter reference table. After reviewing the codebase, the grace period feature is already fully implemented across all relevant files: - `lib/validations.ts` — `toGraceValue()` with clamp [0,7] and schema entry ✅ - `lib/calculate.ts` — `calculateStreak()` accepts `grace` as 4th param ✅ - `app/api/streak/route.ts` — `?grace=` parsed, validated, and passed through ✅ - `lib/calculate.test.ts` — grace=1 and grace=2 behavior already tested ✅ The only missing piece was the README parameter table entry, which this PR adds. Also removes a duplicate parameter table block that existed in README.md. ## Pillar - [x] Other: Documentation ## Fixes Closes JhaSourav07#1714 ## Changes | File | Change | |------|--------| | `README.md` | Added `grace` row to parameter reference table | | `README.md` | Removed duplicate parameter table block | ## New parameter entry | `grace` | `number` | No | `1` | Grace period in days before streak resets (0–7). `grace=0` = strict, `grace=2` = lenient | ## Example URLs now documented
2 parents ad910f3 + 9f29e4d commit 8178782

1 file changed

Lines changed: 61 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 61 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ We render your contribution data as a **3D Isometric City** — a grid of glowin
5555

5656
**Ghost City Architecture:** In this mode, zero-contribution days aren't just empty space. They are rendered as thin, wireframe-style **blueprint foundations** (4px high). This gives your commit landscape a structured, architectural "work-in-progress" look even during rest days, maintaining the premium 3D aesthetic across the entire calendar.
5757

58-
This is not decoration. This is a **live , animated data visualization** that makes your dedication impossible to ignore.
58+
This is not decoration. This is a **live, animated data visualization** that makes your dedication impossible to ignore.
5959

6060
### Why Isometric > Flat
6161

@@ -164,6 +164,7 @@ URL Parameter > Theme Default > System Fallback
164164
| `accent` | `hex` | No | Theme default | Tower & glow color — **without** `#` |
165165
| `text` | `hex` | No | Theme default | Label & stat text color — **without** `#` |
166166
| `radius` | `number` | No | `8` | Border corner radius in pixels |
167+
| `border` | `string` | No | — | Custom stroke color around the main SVG container — **without** `#` |
167168
| `speed` | `string` | No | `8s` | Radar scan duration (`2s`–`20s`, default `8s`) |
168169
| `scale` | `string` | No | `linear` | Tower height scaling: `linear` or `log` (logarithmic) |
169170
| `size` | `string` | No | `medium` | Badge dimensions: `small` (400×280), `medium` (600×420), `large` (800×560) |
@@ -179,30 +180,31 @@ URL Parameter > Theme Default > System Fallback
179180
| `delta_format` | `string` | No | `percent` | Format for month-over-month delta in monthly view: `percent` (e.g. +12%), `absolute` (e.g. +15 commits), or `both` |
180181
| `width` | `number` | No | `300` | Custom width for the SVG canvas (currently only applies to `view=monthly`) |
181182
| `height` | `number` | No | `120` | Custom height for the SVG canvas (currently only applies to `view=monthly`) |
182-
| Parameter | Type | Required | Default | Description |
183-
| ----------------- | --------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
184-
| `user` | `string` | ✅ **Yes** | — | GitHub username to render |
185-
| `theme` | `string` | No | `dark` | Preset theme name (see below) |
186-
| `bg` | `hex` | No | Theme default | Background color — **without** `#` |
187-
| `accent` | `hex` | No | Theme default | Tower & glow color — **without** `#` |
188-
| `text` | `hex` | No | Theme default | Label & stat text color — **without** `#` |
189-
| `radius` | `number` | No | `8` | Border corner radius in pixels |
190-
| `border` | `string` | No | — | Custom stroke color around the main SVG container — **without** `#` |
191-
| `speed` | `string` | No | `8s` | Radar scan duration (`2s`–`20s`, default `8s`) |
192-
| `scale` | `string` | No | `linear` | Tower height scaling: `linear` or `log` (logarithmic) |
193-
| `size` | `string` | No | `medium` | Badge dimensions: `small` (400×280), `medium` (600×420), `large` (800×560) |
194-
| `font` | `string` | No | CommitPulse default typography | Any **Google Font** name (e.g. `Orbitron`, `Inter`) |
195-
| `refresh` | `boolean` | No | `false` | Bypass cache for real-time data |
196-
| `year` | `string` | No | — | Calendar year to render (e.g. `2023`, `2024`) |
197-
| `hide_title` | `boolean` | No | `false` | Hide GitHub username/title from the SVG badge |
198-
| `hide_background` | `boolean` | No | `false` | Remove the background rect, letting the monolith float on the page |
199-
| `hide_stats` | `boolean` | No | `false` | Hides the bottom row displaying Current Streak, Annual Sync Total, and Peak Streak stats when set to `true` or `1`. |
200-
| `tz` | `string` | No | Omitted = UTC | IANA timezone (e.g. `Asia/Kolkata`) — aligns "today" with the user local midnight. Note: `?tz=UTC` is cached separately from omitting `tz`. |
201-
| `lang` | `string` | No | `en` | Language code for labels (`en`, `es`, `hi`, `fr`, `pt`, `ko`, `ja`) |
202-
| `view` | `string` | No | `default` | Rendering mode: `default` (3D Monolith) or `monthly` (Compact monthly stats) |
203-
| `delta_format` | `string` | No | `percent` | Format for month-over-month delta in monthly view: `percent` (e.g. +12%), `absolute` (e.g. +15 commits), or `both` |
204-
| `width` | `number` | No | `300` | Custom width for the SVG canvas (currently only applies to `view=monthly`) |
205-
| `height` | `number` | No | `120` | Custom height for the SVG canvas (currently only applies to `view=monthly`) |
183+
| `grace` | `number` | No | `1` | Grace period in days before a streak resets (0–7). `grace=0` = strict mode (no missed days), `grace=2` = lenient (forgives up to 2 missed days). Default is `1`. |
184+
| `mode` | `string` | No | `commits` | Rendering mode: `commits` (default) or `loc` (Lines of Code landscape) |
185+
| `repo` | `string` | No | — | Render the monolith for a specific repository (e.g. `owner/repo`) instead of the whole profile |
186+
| `org` | `string` | No | — | Organization name to generate a Mega-City for |
187+
| `labels` | `boolean` | No | `false` | Render optional 3D isometric month headers and weekday labels |
188+
| `labelColor` | `hex` | No | — | Custom text color for the isometric labels — **without** `#` |
189+
| `versus` | `string` | No | — | GitHub username of an opponent to compare against in side-by-side versus mode |
190+
| `shading` | `boolean` | No | `false` | Apply intensity-based opacity shading to tower faces so lower intensity levels appear slightly dimmer |
191+
| `gradient` | `boolean` | No | `false` | Opt-in to show volumetric gradients on the monolith floor |
192+
193+
### Grace Period Examples
194+
195+
```md
196+
<!-- Strict mode — streak resets on any single missed day -->
197+
198+
![CommitPulse](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&grace=0)
199+
200+
<!-- Default — one day grace period (current behavior) -->
201+
202+
![CommitPulse](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&grace=1)
203+
204+
<!-- Lenient — forgives up to 2 consecutive missed days -->
205+
206+
![CommitPulse](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&grace=2)
207+
```
206208

207209
### Theme Presets
208210

@@ -214,7 +216,7 @@ URL Parameter > Theme Default > System Fallback
214216
| `dracula` | Dracula Pro | `282a36` | `bd93f9` | `f8f8f2` |
215217
| `github` | GitHub green | `0d1117` | `39d353` | `ffffff` |
216218
| `light` | Clean & minimal | `ffffff` | `0969da` | `24292f` |
217-
| `gruvbox` | retro warm dark | `282828` | `fe8019` | `ebdbb2` |
219+
| `gruvbox` | Retro warm dark | `282828` | `fe8019` | `ebdbb2` |
218220
| `random` | Surprise theme on reload | _varies_ | _varies_ | _varies_ |
219221
| `highcontrast` | Accessibility high contrast | `0a0a0a` | `ff4500` | `ffffff` |
220222
| `cyber-pulse` | AMOLED true-black & cyan | `000000` | `00ffee` | `ffffff` |
@@ -286,6 +288,14 @@ Explore some of the built-in CommitPulse themes and quickly copy the style you l
286288

287289
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&tz=Asia/Kolkata)
288290

291+
<!-- Strict streak — resets on any single missed day -->
292+
293+
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&grace=0)
294+
295+
<!-- Lenient streak — forgives up to 2 missed days -->
296+
297+
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&grace=2)
298+
289299
<!-- Render labels in Hindi -->
290300

291301
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&lang=hi)
@@ -297,6 +307,18 @@ Explore some of the built-in CommitPulse themes and quickly copy the style you l
297307
<!-- Large badge size -->
298308

299309
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&size=large)
310+
311+
<!-- Side-by-side versus comparison -->
312+
313+
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&versus=octocat)
314+
315+
<!-- Lines of Code landscape mode -->
316+
317+
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&mode=loc)
318+
319+
<!-- Gradient + shading for extra depth -->
320+
321+
![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&gradient=true&shading=true)
300322
```
301323

302324
---
@@ -371,6 +393,8 @@ types/index.ts → TypeScript interfaces (StreakStats, BadgePara
371393
---
372394

373395
🏗️ Architecture Diagram
396+
397+
```
374398
GitHub GraphQL API
375399
↓
376400
Contribution Processing
@@ -384,6 +408,7 @@ Animation Layer
384408
Edge Cache/CDN
385409
↓
386410
Generated SVG Badge
411+
```
387412

388413
---
389414

@@ -474,6 +499,16 @@ Yes. Use the `tz` parameter with any valid IANA timezone.
474499
Example:
475500
`?tz=Asia/Kolkata`
476501

502+
### Can I configure the grace period?
503+
504+
Yes. Use the `grace` parameter to control how many days of inactivity are forgiven before your streak resets:
505+
506+
- `?grace=0` — strict mode, resets on any missed day
507+
- `?grace=1` — default behavior (1 day grace)
508+
- `?grace=2` — lenient, forgives up to 2 consecutive missed days
509+
510+
Valid range is 0–7. Values outside this range are clamped automatically.
511+
477512
### Do private contributions count?
478513

479514
Yes — if private contributions visibility is enabled in your GitHub settings.

0 commit comments

Comments
 (0)