Skip to main content

Contributing to Stentorosaur

· 3 min read
Chris
Chris
Amiable Dev
Claude
Claude
AI Assistant

This guide covers setting up a local development environment for Stentorosaur and the contribution workflow.

Foundation​

Stentorosaur builds on Upptime. If you're interested in standalone status pages (not Docusaurus-integrated), consider contributing to Upptime instead.

Quick Start​

Prerequisites: Node.js 18+, npm 9+

# Clone the repository
git clone https://github.com/amiable-dev/docusaurus-plugin-stentorosaur.git
cd docusaurus-plugin-stentorosaur

# Install dependencies
npm ci

# Run tests
npm test

# Build the plugin
npm run build

# Run the example site (includes the plugin)
npm run start:example

The example site at examples/test-site/ is pre-configured with the plugin linked locally. Changes to src/ are reflected after rebuild.

Repository Structure​

docusaurus-plugin-stentorosaur/
├── src/
│   ├── index.ts                    # Plugin entry point
│   ├── types.ts                    # TypeScript types (incl. DataSource)
│   ├── options.ts                  # Joi validation schemas
│   ├── github-service.ts           # GitHub API interactions
│   ├── data-source-resolver.ts     # DataSource URL resolution (server)
│   ├── data-source-resolver.client.ts  # Client-safe resolver (browser)
│   ├── data-source-validator.ts    # Zod validation + security checks
│   ├── hooks/
│   │   ├── index.ts                # Hook exports
│   │   └── useStatusData.ts        # Runtime data fetching hook
│   ├── theme/                      # React components for /status page
│   └── notifications/              # Slack/Discord/Email providers
├── scripts/                        # CLI tools (monitor, notify, etc.)
├── __tests__/                      # Jest test files
├── docs/
│   └── adrs/                       # Architecture Decision Records
└── lib/                            # Compiled output (generated)

Key files added in v0.16 (ADR-001):

  • data-source-resolver.ts / data-source-resolver.client.ts — URL building for different strategies
  • data-source-validator.ts — Zod schema validation and security checks
  • hooks/useStatusData.ts — React hook for runtime data fetching

Ways to Contribute​

Report Issues​

Found a bug? Open an issue with:

**Description:** SLO chart shows incorrect percentage after DST change

**Steps to Reproduce:**
1. Configure SLO target at 99.9%
2. Wait for DST time change
3. View SLO chart

**Expected:** 99.5% actual uptime
**Actual:** 102.3% (impossible value)

**Environment:**
- Plugin version: 0.13.1
- Docusaurus version: 3.9.0
- Node.js version: 20.10.0

Fix Bugs or Add Features​

  1. Check existing issues for duplicates or related discussions
  2. Open an issue first if the change is non-trivial (API changes, new features)
  3. Fork and clone the repository
  4. Create a branch: git checkout -b fix/slo-dst-bug
  5. Make changes in src/, add tests in __tests__/
  6. Run checks: 
    npm run build && npm test && npm run lint
  7. Submit a PR with a clear description

Fix Documentation​

Documentation lives in the README and this blog. For quick fixes:

  1. Fork the repo
  2. Edit markdown files
  3. Submit PR: docs: Fix typo in notification setup

Code Style​

TypeScript:

  • Strict mode enabled
  • Interfaces over type aliases for object shapes
  • Discriminated unions for type-safe state

React (theme components):

  • Functional components with hooks
  • CSS Modules for styling
  • ARIA labels for accessibility

Tests:

  • Jest with ts-jest
  • Mock external APIs (@octokit/rest, fetch)
  • Match file structure: src/foo.ts → __tests__/foo.test.ts

Commits:

  • Conventional Commits: feat:, fix:, docs:, test:, chore:
  • Reference issues: fix: Handle DST in SLO chart (#123)

PR Checklist​

Before submitting:

  • Tests pass (npm test)
  • Build succeeds (npm run build)
  • Lint passes (npm run lint)
  • Tests added for new code
  • CHANGELOG.md updated (if user-facing change)
  • Documentation updated (if API changed)

Testing Gaps​

Current coverage: ~80% lines, ~70% branches. Areas needing tests:

  • Theme components (need jsdom/RTL setup)
  • Chart.js rendering
  • Edge cases in date/timezone handling
  • Multi-channel notification scenarios

Run coverage report:

npm test -- --coverage

Getting Help​

  • Check existing issues and PRs
  • Open a discussion for questions
  • PRs are typically reviewed within 72 hours

License​

Contributions are licensed under MIT (same as the project).