Testing and Contributing

Contributions should preserve StarryBio’s core promise: a strict, configurable static profile site that builds one portable artifact for GitHub Pages, Cloudflare Workers, Vercel, Netlify, and future static hosts.

Choose the right starting point

• For a site configuration/support question, read this wiki—especially Troubleshooting—before opening an issue.
• For a reproducible product bug, use the repository’s bug report form.
• For a theme or layout proposal, use the theme/layout proposal form.
• For an analytics provider proposal, use the analytics provider proposal form.
• For a security issue, use private GitHub Security Advisory reporting, not a public issue.

Review the repository’s CONTRIBUTING.md, Code of Conduct, and Security Policy before submitting a contribution.

Branch and local workflow

1. Fork and clone the repository.

2. Create a focused branch, such as fix/status-timezone or feat/aurora-theme.

3. Install dependencies and start the site.

   pnpm install
   pnpm dev

4. Make the smallest coherent change. Avoid unrelated formatting or refactors in the same pull request.

5. Add tests and documentation with the implementation.

The public starter configuration in config/starrybio.config.ts is part of the project experience. When a configuration feature changes, keep the schema, example configuration, generator behavior, user wiki, and tests aligned.

Test layers

Formatting, linting, types, and unit tests

pnpm check

pnpm check runs formatting verification, ESLint, astro check, tsc --noEmit, and unit tests. Use pnpm format if Prettier reports a formatting difference.

Downstream tests

pnpm test

This runs the portable unit and integration suites for a downstream deployment.

Unit tests

pnpm test:unit

Vitest unit tests cover isolated schema, normalization, runtime, generator, security-header, and updater behavior. Place narrow regression tests alongside the relevant existing tests/unit/*.test.ts topic.

Integration builds

pnpm test:integration

This builds minimal and heavily customized configurations in temporary project copies without replacing the installation’s configuration or assets.

Browser tests

pnpm test:e2e

This builds the active configuration and runs Playwright. Expectations are derived from that configuration, and disabled optional features are skipped.

Fixture browser tests

pnpm test:e2e:fixtures

This runs deterministic browser deployments for minimal and heavily customized configurations.

Upstream repository checks

pnpm test:upstream

This checks StarryBio’s stock assets, starter metadata, and maintainer workflows. It is for upstream release work, not downstream deployments.

Full release gate

pnpm release:check

This runs pnpm check, integration and upstream checks, active-config and fixture browser tests, and pnpm audit. It does not publish a release or deploy to Cloudflare.

Change-specific expectations

Change	Minimum additional care
Schema/configuration	Add accept/reject/default tests; document the field; preserve strict validation.
Theme/layout/CSS	Check desktop and mobile, keyboard focus, contrast, and reduced motion.
Status logic	Cover timezone-local semantics, overnight intervals, overlap ordering, and exclusive end times.
Generated assets	Test correct output, escaping, invalid paths/extensions, and stale-file cleanup.
Analytics	Add schema/descriptors/tests, keep HTTPS and no-inline-script model, tighten CSP.
Deployment config	Keep the build provider-neutral, preserve header parity, and test/document each affected host.
New visible behavior	Update both the relevant user wiki page and the configuration starter/example.

Pull request hygiene

1. Keep the PR focused and explain the user-visible outcome.
2. Link a prior issue for substantial features, themes, layouts, or provider integrations.
3. Include screenshots or a recording for visual changes, including narrow-screen results.
4. Record commands and results in the pull-request template.
5. Use a clear Conventional Commit-style title, for example fix: preserve overnight status schedules or feat: add aurora theme preset.
6. Never commit real analytics identifiers tied to a private account, Cloudflare credentials, or other secrets; use placeholders in examples and tests.

Documentation changes

The wiki is the detailed operator documentation. Update it when behavior, settings, deployment, security, or troubleshooting changes. Keep README concise and point readers to the wiki rather than duplicating whole configuration guides in repository landing-page documentation.

If code behavior and documentation disagree, fix the mismatch in the same contribution. When you cannot verify a platform behavior from the repository or primary vendor documentation, do not state it as a StarryBio feature.