mirror of
https://github.com/samsonjs/samhuri.net.git
synced 2026-03-25 09:05:47 +00:00
Sami Samhuri
007b1058b6
Replace the Swift site generator with a Ruby and Phlex implementation. Loads site and projects from TOML, derive site metadata from posts. Migrate from make to bake and add standardrb and code coverage tasks. Update CI and docs to match the new workflow, and remove unused assets/dependencies plus obsolete tooling.
75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
This repository is a single Ruby static-site generator project (the legacy Swift generators were removed).
|
|
|
|
- Generator code: `lib/pressa/` (entrypoint: `lib/pressa.rb`)
|
|
- Build/deploy/draft tasks: `bake.rb`
|
|
- Tests: `test/`
|
|
- Site config: `site.toml`, `projects.toml`
|
|
- Published posts: `posts/YYYY/MM/*.md`
|
|
- Static and renderable public content: `public/`
|
|
- Draft posts: `public/drafts/`
|
|
- Generated output: `www/` (safe to delete/regenerate)
|
|
|
|
Keep new code under the existing `Pressa` module structure (for example `lib/pressa/posts`, `lib/pressa/projects`, `lib/pressa/views`, `lib/pressa/config`, `lib/pressa/utils`) and add matching tests under `test/`.
|
|
|
|
## Setup, Build, Test, and Development Commands
|
|
- Use `rbenv exec` for Ruby commands in this repository (for example `rbenv exec bundle exec ...`) to ensure the project Ruby version is used.
|
|
- `bin/bootstrap`: install prerequisites and gems (uses `rbenv` when available).
|
|
- `rbenv exec bundle exec bake debug`: build for `http://localhost:8000` into `www/`.
|
|
- `rbenv exec bundle exec bake serve`: serve `www/` via WEBrick on port 8000.
|
|
- `rbenv exec bundle exec bake watch target=debug`: Linux-only autorebuild loop (`inotifywait` required).
|
|
- `rbenv exec bundle exec bake mudge|beta|release`: build with environment-specific base URLs.
|
|
- `rbenv exec bundle exec bake publish_beta|publish`: build and rsync `www/` to remote host.
|
|
- `rbenv exec bundle exec bake clean`: remove `www/`.
|
|
- `rbenv exec bundle exec bake test`: run test suite.
|
|
- `rbenv exec bundle exec bake lint`: lint code.
|
|
- `rbenv exec bundle exec bake lint_fix`: auto-fix lint issues.
|
|
- `rbenv exec bundle exec bake coverage`: run tests and report `lib/` line coverage.
|
|
- `rbenv exec bundle exec bake coverage_regression baseline=merge-base`: compare coverage to a baseline and fail on regression (override `baseline` as needed).
|
|
|
|
## Draft Workflow
|
|
- `rbenv exec bundle exec bake new_draft "Post Title"` creates `public/drafts/<slug>.md`.
|
|
- `rbenv exec bundle exec bake drafts` lists available drafts.
|
|
- `rbenv exec bundle exec bake publish_draft public/drafts/<slug>.md` moves draft to `posts/YYYY/MM/` and updates `Date` and `Timestamp`.
|
|
|
|
## Content and Metadata Requirements
|
|
Posts must include YAML front matter. Required keys (enforced by `Pressa::Posts::PostMetadata`) are:
|
|
|
|
- `Title`
|
|
- `Author`
|
|
- `Date`
|
|
- `Timestamp`
|
|
|
|
Optional keys include `Tags`, `Link`, `Scripts`, and `Styles`.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Ruby (see `.ruby-version`).
|
|
- Follow idiomatic Ruby style and keep code `bake lint`-clean.
|
|
- Use 2-space indentation and descriptive `snake_case` names for methods/variables, `UpperCamelCase` for classes/modules.
|
|
- Prefer small, focused classes for plugins, views, renderers, and config loaders.
|
|
- Do not hand-edit generated files in `www/`.
|
|
|
|
## Testing Guidelines
|
|
- Use Minitest under `test/` (for example `test/posts`, `test/config`, `test/views`).
|
|
- Add regression tests for parser, rendering, feed, and generator behavior changes.
|
|
- Before submitting, run:
|
|
- `rbenv exec bundle exec bake test`
|
|
- `rbenv exec bundle exec bake coverage`
|
|
- `rbenv exec bundle exec bake lint`
|
|
- `rbenv exec bundle exec bake debug`
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Use concise, imperative commit subjects (history examples: `Fix internal permalink regression in archives`).
|
|
- Keep commits scoped to one concern (generator logic, content, or deployment changes).
|
|
- In PRs, include motivation, verification commands run, and deployment impact.
|
|
- Include screenshots when changing rendered layout/CSS output.
|
|
|
|
## Deployment & Security Notes
|
|
- Deployment is defined in `bake.rb` via rsync over SSH.
|
|
- Current publish host is `mudge` with:
|
|
- production: `/var/www/samhuri.net/public`
|
|
- beta: `/var/www/beta.samhuri.net/public`
|
|
- Validate `www/` before publishing to avoid shipping stale assets.
|
|
- Never commit credentials, SSH keys, or other secrets.
|