feat: initial release of volumen — a file-based Markdown blog engine
This commit is contained in:
+257
@@ -0,0 +1,257 @@
|
||||
# Contributing
|
||||
|
||||
Thank you for considering contributing to **volumen** — a small, file-based
|
||||
Markdown blog engine written in CRuby, with a built-in admin and a public JSON
|
||||
API.
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Requirements
|
||||
|
||||
- **Ruby ≥ 3.3** with a C toolchain (Puma compiles a native extension).
|
||||
- Fedora: `sudo dnf install ruby ruby-devel @development-tools openssl-devel`
|
||||
- Debian/Ubuntu: `sudo apt install ruby-full build-essential libssl-dev`
|
||||
- [`just`](https://github.com/casey/just) — the `justfile` is the source of
|
||||
truth for install / run / build / test / uninstall.
|
||||
- Linux, macOS, or FreeBSD.
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
git clone https://codeberg.org/petrbalvin/volumen.git
|
||||
cd volumen
|
||||
just install # bundle install
|
||||
just test # bundle exec rake test (minitest)
|
||||
just build # rubocop (zero warnings) + gem build → pkg/volumen.gem
|
||||
just dev # run against ./posts and ./config.toml on :9090
|
||||
```
|
||||
|
||||
`just dev` serves the bundled sample posts and a local `config.toml`. The dev
|
||||
admin password is `admin` (the hash lives in `./config.toml`). Open
|
||||
<http://localhost:9090/admin/>.
|
||||
|
||||
For a fresh `serve` (without `--config`), the first run writes a commented
|
||||
template to `/etc/volumen/config.toml`; see [`docs/deployment.md`](docs/deployment.md).
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
just test
|
||||
```
|
||||
|
||||
The minitest suite (`test/`) covers:
|
||||
|
||||
- `frontmatter` — `+++` TOML block parse/serialise round-trips.
|
||||
- `post` / `store` — the Post model, reading/writing posts and media.
|
||||
- `markdown` — GFM rendering (tables, fenced code).
|
||||
- `config` — defaults, overrides, template generation.
|
||||
- `password` / `users` — scrypt hashing, roles, last-admin safeguards.
|
||||
- `server` / `admin` — the JSON API and the admin (auth, CSRF, CRUD, uploads,
|
||||
roles) via `rack-test`.
|
||||
|
||||
### Linting
|
||||
|
||||
RuboCop is the source of truth for style (`.rubocop.yml`). The project enforces
|
||||
**zero offenses**:
|
||||
|
||||
```bash
|
||||
bundle exec rubocop # check (also run as part of `just build`)
|
||||
bundle exec rubocop -A # autocorrect
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
- Idiomatic Ruby; let RuboCop guide you. CI fails on any offense.
|
||||
- **Two-space** indentation, **double quotes**, and `# frozen_string_literal: true`
|
||||
at the top of every Ruby file.
|
||||
- Document every class/module with a short comment (`Style/Documentation` is on).
|
||||
- Keep lines ≤ 100 characters (`Layout/LineLength`).
|
||||
- Prefer guard clauses; return `nil`/objects for expected "not found" cases
|
||||
rather than raising.
|
||||
- Keep the dependency set small and deliberate — runtime gems are `sinatra`,
|
||||
`kramdown` (+ `kramdown-parser-gfm`), `toml-rb`, `puma`, `rackup`. Crypto uses
|
||||
the standard library (`openssl`, `securerandom`). New runtime dependencies
|
||||
should be discussed in an issue first.
|
||||
- Admin content is authored by trusted users; see [`docs/security.md`](docs/security.md)
|
||||
for the trust model before touching rendering or uploads.
|
||||
|
||||
### Testing
|
||||
|
||||
- Put tests in `test/*_test.rb`, each starting with `require "test_helper"`.
|
||||
- Use `Dir.mktmpdir` for anything touching the filesystem; never assume a clean
|
||||
working directory.
|
||||
- Exercise the HTTP layer with `Rack::Test` (`Volumen::Server.configured(...)`).
|
||||
- Name tests `test_<thing>_<scenario>`; cover both the happy and the error path.
|
||||
|
||||
## Commit Conventions
|
||||
|
||||
We follow [Conventional Commits](https://www.conventionalcommits.org/).
|
||||
|
||||
| Type | Use |
|
||||
|------------|----------------------------------------------|
|
||||
| `feat` | New feature |
|
||||
| `fix` | Bug fix |
|
||||
| `refactor` | Restructuring without behaviour change |
|
||||
| `docs` | Documentation |
|
||||
| `test` | Adding or updating tests |
|
||||
| `chore` | Maintenance, CI, tooling |
|
||||
| `perf` | Performance improvement |
|
||||
| `style` | Formatting / lint-only changes |
|
||||
| `security` | Hardening without a user-visible fix |
|
||||
|
||||
```
|
||||
feat: add author role with last-admin safeguards
|
||||
fix: rename Server.build to .configured to avoid a Sinatra clash
|
||||
refactor: extract frontmatter parsing into its own module
|
||||
docs: document the dual-mode editor
|
||||
test: cover GFM table and fenced code rendering
|
||||
chore: pin gem versions to latest
|
||||
```
|
||||
|
||||
- English, lowercase subject, imperative mood (`add`, not `added`).
|
||||
- No trailing period, max 72 characters.
|
||||
- No version numbers in commit messages — versions belong to tags.
|
||||
|
||||
## Pull Request Flow
|
||||
|
||||
1. Create a feature branch from `development`.
|
||||
2. Make your changes with Conventional-Commits messages.
|
||||
3. Ensure `bundle exec rubocop` reports zero offenses and `just test` passes.
|
||||
4. Add or update tests for your change.
|
||||
5. Update documentation if the public API, configuration, or behaviour changes:
|
||||
- `README.md` — high-level overview.
|
||||
- `docs/configuration.md` — config keys.
|
||||
- `docs/api-reference.md` — JSON API behaviour.
|
||||
- `docs/architecture.md` — structural changes.
|
||||
- `docs/security.md` — anything touching auth, uploads, or rendering.
|
||||
6. Open a pull request against `development`. Releases are cut by merging
|
||||
`development` into `main` and pushing a `vX.Y.Z` tag — see
|
||||
[Cutting a release](#cutting-a-release).
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
volumen/
|
||||
├── exe/
|
||||
│ └── volumen # CLI: serve, hash-password, version, help
|
||||
├── lib/
|
||||
│ ├── volumen.rb # library entry (requires the core modules)
|
||||
│ └── volumen/
|
||||
│ ├── version.rb
|
||||
│ ├── frontmatter.rb # parse/serialise the +++ TOML frontmatter block
|
||||
│ ├── markdown.rb # kramdown (GFM) → HTML
|
||||
│ ├── post.rb # Post model (metadata + body + rendered HTML)
|
||||
│ ├── store.rb # read/write posts and media on disk
|
||||
│ ├── config.rb # load/merge config.toml, generate template
|
||||
│ ├── password.rb # scrypt hashing/verification (OpenSSL::KDF)
|
||||
│ ├── users.rb # users.toml, admin/author roles
|
||||
│ ├── server.rb # Sinatra app: public API + admin
|
||||
│ ├── cli.rb # command dispatcher
|
||||
│ └── web/
|
||||
│ ├── views/ # ERB templates (layout, login, list, form, settings)
|
||||
│ └── public/ # static assets (volumen-logo.svg)
|
||||
├── test/ # minitest suite
|
||||
├── docs/ # architecture, configuration, api-reference, deployment, security
|
||||
├── .forgejo/workflows/ # test.yml, release.yml (Forgejo Actions)
|
||||
├── justfile # install, run, dev, build, test, uninstall
|
||||
├── volumen.gemspec
|
||||
├── Gemfile
|
||||
├── CHANGELOG.md
|
||||
└── LICENSE
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Browser[Browser / Vue SPA]
|
||||
Nginx[nginx reverse proxy]
|
||||
Server[Volumen::Server -- Sinatra]
|
||||
Store[Volumen::Store]
|
||||
Markdown[Volumen::Markdown -- kramdown GFM]
|
||||
Users[Volumen::Users]
|
||||
Posts[(content_dir/*.md)]
|
||||
UsersFile[(users.toml)]
|
||||
|
||||
Browser -->|GET /api/volumen/*| Nginx
|
||||
Browser -->|/admin| Nginx
|
||||
Nginx --> Server
|
||||
Server -->|read/write posts| Store
|
||||
Server -->|render Markdown| Markdown
|
||||
Server -->|auth + roles| Users
|
||||
Store --> Posts
|
||||
Users --> UsersFile
|
||||
```
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
- **File-based, no database** — every post is a `.md` file with TOML
|
||||
frontmatter; users live in a `users.toml`. Everything is plain text, safe to
|
||||
commit and back up.
|
||||
- **Headless for the front-end** — volumen serves a read-only JSON API and its
|
||||
own server-rendered admin; the public site is a separate consumer.
|
||||
- **Single universal gem** — volumen is pure Ruby, so `gem build` produces one
|
||||
platform-independent gem. Only the `puma` dependency has a native extension,
|
||||
compiled at install time on the host.
|
||||
- **Trusted authors** — kramdown passes raw HTML through on purpose; content is
|
||||
only as safe as who can log in (see `docs/security.md`).
|
||||
- **Roles, server-enforced** — `admin` manages users, `author` manages posts
|
||||
and their own account; `require_admin!` gates user management on the server,
|
||||
with last-admin safeguards.
|
||||
|
||||
## CI
|
||||
|
||||
volumen uses **Forgejo Actions**; both workflows live under `.forgejo/workflows/`
|
||||
and run on the `codeberg-small` runner.
|
||||
|
||||
### Test — `.forgejo/workflows/test.yml`
|
||||
|
||||
Triggered on push and pull requests targeting `development`.
|
||||
|
||||
| Job | What it does |
|
||||
|--------|-----------------------------------------------|
|
||||
| `lint` | `bundle exec rubocop` (must report zero offenses) |
|
||||
| `test` | `bundle exec rake test` on a Ruby `3.3` / `3.4` matrix |
|
||||
|
||||
Run the same locally before opening a PR:
|
||||
|
||||
```bash
|
||||
bundle exec rubocop
|
||||
just test
|
||||
```
|
||||
|
||||
### Release — `.forgejo/workflows/release.yml`
|
||||
|
||||
Triggered by pushing a `v*` tag. It verifies the tag matches `Volumen::VERSION`,
|
||||
runs the quality gate (rubocop + tests), builds `volumen-X.Y.Z.gem`, extracts
|
||||
the matching `CHANGELOG.md` section, creates a Forgejo release via the REST API,
|
||||
and attaches the gem. It does **not** publish to RubyGems.
|
||||
|
||||
Requires a `FORGEJO_TOKEN` secret with permission to create releases.
|
||||
|
||||
### Cutting a release
|
||||
|
||||
1. Bump `VERSION` in `lib/volumen/version.rb`.
|
||||
2. Add a `## [X.Y.Z] — YYYY-MM-DD` section at the top of `CHANGELOG.md`.
|
||||
3. Ensure CI is green on `development`.
|
||||
4. Merge `development` into `main` (the only time `main` changes outside a tag).
|
||||
5. Tag and push:
|
||||
```bash
|
||||
git tag -a vX.Y.Z -m "volumen vX.Y.Z"
|
||||
git push origin main
|
||||
git push origin vX.Y.Z
|
||||
```
|
||||
6. The release workflow builds the gem and publishes the release from the
|
||||
CHANGELOG section.
|
||||
|
||||
## Report a Bug
|
||||
|
||||
Open an issue at <https://codeberg.org/petrbalvin/volumen/issues> with:
|
||||
|
||||
- volumen version (`volumen version`).
|
||||
- Operating system and architecture.
|
||||
- Exact steps (request or admin action) that reproduce it.
|
||||
- Expected vs actual behaviour, and the relevant slice of `journalctl -u volumen`.
|
||||
|
||||
For **security issues**, please email **opensource@petrbalvin.org** rather than
|
||||
opening a public issue.
|
||||
Reference in New Issue
Block a user