From 5d2e75016da7412f0ed9ceb80d09c4a849c91f46 Mon Sep 17 00:00:00 2001 From: Domini Montessori Date: Fri, 9 Oct 2026 06:28:30 +0300 Subject: [PATCH 1/6] docs: clarify project architecture and site workflow --- AGENTS.md | 8 +- README.md | 184 ++++++++++++++++--------------------------- docs/ARCHITECTURE.md | 104 ++++++++++++------------ 3 files changed, 124 insertions(+), 172 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e4e4e5ee8..5c7210365 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,8 @@ > production SSG and stays — no migration to Astro/Jekyll. `docs/SSG_MIGRATION_PLAN.md` > is **superseded** (its original plan was based on a stale snapshot); `docs/STRATEGIC_PLAN_2026-2027.md` > carries a stale baseline — see its reconciliation header. Source of truth for -> current state: this file + `ROADMAP.md` + `AUDIT-2026-08.md`. +> current state: this file + `docs/ROADMAP_STATUS.md` + +> `docs/architecture/AUDIT-2026-08.md`. ## Overview @@ -113,6 +114,7 @@ in CI, so the version there is authoritative. | Lines | 76.57% | This is the **official baseline** (not the aspirational 85% target, which -requires an E2E/Playwright layer — tracked in `ROADMAP.md` / `AUDIT-2026-08.md`, -not in the (stale-baseline) `STRATEGIC_PLAN_2026-2027.md`. +requires an E2E/Playwright layer — tracked in `docs/ROADMAP_STATUS.md` / +`docs/architecture/AUDIT-2026-08.md`, not in the (stale-baseline) +`STRATEGIC_PLAN_2026-2027.md`. Do not regress below these numbers on the `src/` plane without adding tests. diff --git a/README.md b/README.md index abcb73b31..6ef6f75c6 100644 --- a/README.md +++ b/README.md @@ -1,122 +1,74 @@ -# dominicusin.github.io — Engineering Blog (Hugo + Blowfish) +# dominicusin.github.io -[![Deploy](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml/badge.svg)](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml) -[![Tests](https://img.shields.io/badge/tests-277%20jest%20%2B%209%20hardhat-brightgreen)](tests/) +[![Pages](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml/badge.svg)](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -> Static engineering blog built with **Hugo** + the **Blowfish** theme, deployed to GitHub Pages. -> Migrated from the legacy Jekyll + esbuild stack (see `docs/SSG_MIGRATION_PLAN.md`). - -Domini's personal engineering blog: industrial engineering, systems engineering, and data science, -plus decentralized-web / DAO notes. - -## 🚀 Architecture (two planes) - -This repository deliberately separates **publishing** from **engineering tooling**: - -- **Publishing Plane** — the website. - - Generator: Hugo (extended) + Blowfish theme (git submodule at `themes/blowfish`). - - Content: `content/` (blog posts in `content/blog/`, `content/people/`, `content/domini/`). - - Config: `config/_default/` (`hugo.toml`, `config.toml`, `params` inline, `menus.*.toml`, `languages.toml`). - - Comments: [giscus](https://giscus.app) (GitHub Discussions backend, category "Announcements"). - - Subscription: Buttondown form (`layouts/partials/subscription.html`). - - i18n: `i18n/{ru,en}.yaml` (ru default, en secondary). - - Build/deploy: `.github/workflows/hugo.yml` → GitHub Pages (single publisher). -- **Engineering Plane** — smart-contract / DAO tooling (kept separate, NOT deployed to the site). - - `contracts/dao/` — Solidity sources. - - `tests/hardhat/` — Hardhat tests (`npx hardhat test`, 9 passing). - - `scripts/` — content-contract + knowledge-graph generation. - - `src/` — v4.0 frontend modules (CRDT/P2P/DAO/BCI adapters). Retained for the engineering - substrate; not bundled into the static site (Hugo ignores `src/`). - -See [`docs/adr/0002-two-plane-architecture.md`](docs/adr/0002-two-plane-architecture.md) for the -formal two-plane boundary, integration points, and DAO lifecycle. - -## 🛠 Local development - -```bash -# 1. Install Hugo (extended) — e.g. via Go: -# CGO_ENABLED=0 go install github.com/gohugoio/hugo@v0.164.0 -# 2. Init the theme submodule: -git submodule update --init --recursive -# 3. Run the dev server (drafts included): +Personal engineering blog and knowledge library: [dominicusin.github.io](https://dominicusin.github.io/). +The public site is built with Hugo and the Blowfish theme, with Russian as its primary language. + +## How the project fits together + +The repository has two clear parts: + +- **Website:** Hugo content, templates, theme, and generated site data. This is the only part published to GitHub Pages. +- **Engineering archive:** `src/`, `contracts/dao/`, and their tests. These are retained experiments; they are not shipped with the site. + +The architecture boundary and its rationale are recorded in +[`docs/adr/0002-two-plane-architecture.md`](docs/adr/0002-two-plane-architecture.md). +The current implementation overview is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). + +## Build and preview the site + +Requirements: Node.js 24, Hugo Extended 0.164.0, and the Blowfish theme submodule. + +```sh +git submodule update --init themes/blowfish +npm ci --prefix scripts +node scripts/sync-github.cjs +node scripts/build-knowledge-graph.cjs +node scripts/build-ontology-feed.cjs +node scripts/build-crosslinks.cjs +node scripts/build-awesome.cjs hugo server -D -# 4. Production build: -hugo --gc --minify ``` -The site is served from `public/` after a build. `public/` and `resources/` are git-ignored. - -## 📦 Content model - -- Posts live in `content/blog/` as `YYYY-MM-DD-slug.md`. Frontmatter is normalized - (title, date ISO-8601, categories, tags, authors, draft, slug). -- Legacy permalinks are preserved via Hugo `aliases` (e.g. `/2015/11/19/first.html` → `/2015/11/19/first/`). -- The `content/posts` → `content/blog` rename keeps post URLs intact; `/posts/` now aliases `/blog/`. -- Every **new** post (added in a PR) is validated as a **hard gate** against - `schema/post-metadata.schema.json` in CI (`scripts/ci-content-contract.cjs`): - an invalid new post **blocks the deploy**. Modified legacy posts (e.g. 2015 - posts lacking tags/author) are report-only and do not block. -- Author hint: run `node scripts/ci-content-contract.cjs` locally before push to - self-check; `node scripts/validate-frontmatter.cjs content/blog/` validates a single post. - -## 🔧 Key files - -| Path | Purpose | -|------|---------| -| `config/_default/hugo.toml` | Site + Blowfish params, permalinks, outputs, giscus, subscription URL | -| `config/_default/config.toml` | `theme = "blowfish"` declaration | -| `themes/blowfish` | Theme submodule (v2.105.0) | -| `content/` | All site content | -| `layouts/partials/comments.html` | giscus + subscription injection | -| `i18n/` | ru/en translations | -| `contracts/dao/`, `tests/hardhat/` | DAO engineering plane | -| `.github/workflows/hugo.yml` | The only GitHub Pages publisher | - -## ⚙️ CI/CD (single publisher model) - -Only `.github/workflows/hugo.yml` deploys to GitHub Pages. Other workflows are -quality/support and never flip the Pages source. - -| Workflow | Purpose | Deploys? | -|----------|---------|----------| -| `hugo.yml` | Build + **content-contract hard gate (new posts)** + deploy to Pages | ✅ yes | -| `hugo-build-check.yml` | Build-only sanity check | ❌ | -| `security.yml` | Node audit + Trivy + Semgrep (weekly) | ❌ | -| `performance.yml` | Lighthouse audit against live Pages URL | ❌ | -| `dependency-update.yml` | Dependabot-driven bumps | ❌ | -| `link-repair.yml` | Scheduled broken-link check | ❌ | -| `deploy-dao.yml` | `test` job (Hardhat, no secrets) + guarded `deploy` (needs secrets) | ❌ (separate track) | -| `vr-export.yml` | Build-only VR artifact (no Pages flip) | ❌ | -| `sync_gists.yml`, `analytics.yml`, `fediverse-notify.yml` | Post-deploy integrations | ❌ | -| `deploy-ipfs.yml` | **DISABLED** (legacy Jekyll + compromised Pinata) | ❌ | - -> The legacy Jekyll CI (`ci.yml`, `jekyll.yml`, `ci-cd.yml`) was removed in -> Phase 7. Do not reintroduce `bundle exec jekyll build` — the site is Hugo-only. - -## 🧠 Knowledge Hub (Engineering Knowledge Platform) - -The site is more than a blog: it is a navigable knowledge base. - -- **Knowledge Graph** (`/knowledge-graph/`) — interactive concept/post explorer - backed by `/data/knowledge-graph.json` (JSON-LD, generated each build). Noscript - fallback via `/categories/` + `/tags/`. -- **Community** (`/community/`) — giscus (GitHub Discussions) comments + Buttondown - subscription, with discussion norms and a privacy note. -- **Editorial strategy**: `docs/EDITORIAL_STRATEGY.md` (content directions, taxonomy, - people/domini rules, author checklist). -- **DAO track**: `docs/DAO_ROADMAP.md` (contracts, test/deploy, threat model). -- **Architecture**: `docs/adr/0002-two-plane-architecture.md` (Publishing vs Engineering). -- **Content contract**: `docs/CONTENT_CONTRACT.md` (new posts are a hard gate). - -## 🧹 Legacy (removed) - -The legacy Jekyll + esbuild stack (`_config.yml`, `Gemfile`, `_layouts/`, `_includes/`, -`_sass/`, `_posts/`, `_site/`, `js/`, `build.js`, `build-jekyll.rb`) and the Jekyll CI workflows -(`ci.yml`, `jekyll.yml`, `ci-cd.yml`) were **removed** in Phase 7 (rollback point tagged -`pre-phase7-legacy`). The Hugo site is the sole publisher. `src/` (DAO/CRDT modules) and -`contracts/dao/` are retained as the engineering plane. - -## 📄 License - -MIT — see `LICENSE`. +Open the local URL printed by Hugo. To create the production output in `public/`: + +```sh +hugo --gc --minify --baseURL "https://dominicusin.github.io/" +``` + +The deploy workflow runs the data generators and Hugo build in this order, then publishes the `public/` artifact to GitHub Pages. Pushes to `main` and the scheduled repository sync both use this workflow. The `quality.yml` workflow checks pull requests and never deploys. + +## Where to work + +| Area | Source of truth | +| --- | --- | +| Posts and pages | `content/` | +| Site settings and navigation | `config/_default/` | +| Theme overrides | `layouts/`, `assets/`, `static/`, `i18n/` | +| Generated site data | `data/`, `static/data/`, generated by `scripts/` | +| Content rules | `schema/post-metadata.schema.json`, `docs/CONTENT_CONTRACT.md` | +| Publishing and operations | `docs/PUBLISHING.md`, `docs/OPERATIONS.md` | +| Frozen engineering archive | `src/`, `contracts/dao/`, `tests/` | + +New articles belong in `content/blog/`. Keep front matter aligned with the content schema; CI checks new articles before they can be published. Use Hugo aliases when changing a page URL so existing links continue to work. + +## Project checks + +The required pull request gate is the **Quality CI** workflow. It installs the root Node dependencies, builds Hugo, checks content and internal links, and runs the repository lint step. The separate R&D workflow handles the retained JavaScript and Solidity suites for changes to those areas. + +Useful local commands: + +```sh +npm ci +npm run lint +npm test +npx hardhat test +``` + +These commands cover the engineering archive. The site build uses the nested tooling dependencies installed with `npm ci --prefix scripts`. + +## License + +MIT. See [`LICENSE`](LICENSE). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 26e303ee3..0f24b10da 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,59 +1,57 @@ # Architecture -> **Status (2026-08-15):** The site is published by **Hugo + Blowfish** (single -> publisher, `hugo.yml` → GitHub Pages). The legacy Jekyll + esbuild stack was -> removed in Phase 7. `src/` is retained as an **engineering substrate** that -> Hugo does NOT bundle. See `docs/adr/0002-two-plane-architecture.md` for the -> formal boundary. +The repository has one public product: a static Hugo site. GitHub Actions builds it with Hugo Extended 0.164.0 and the Blowfish v2.105.0 theme, then publishes the generated `public/` directory to GitHub Pages. + +## Repository map + +```text +content/ Published articles, profiles, and reference pages +config/_default/ Hugo settings, language setup, and navigation +layouts/ Hugo templates and site-specific theme overrides +assets/ static/ i18n/ Styles, images, public files, and translations +data/ scripts/ Source data and build-time generators +schema/ Article metadata contract +themes/blowfish/ Hugo theme submodule +src/ contracts/ tests/ Retained engineering experiments and test suites +.github/workflows/ Build, quality, security, and integration automation +``` -## Two planes +`content/`, `config/`, `layouts/`, theme overrides, and generated data form the publishing path. `src/` and `contracts/dao/` are an independent, retained R&D archive; Hugo does not bundle them into the website. Their tests run in a separate workflow. -``` -repository root -├── content/ # Publishing plane — Markdown posts/pages -├── config/ # Hugo config (_default/) -├── layouts/ # partials (giscus, subscription) -├── assets/ # og-default.svg, lib/fuse (search) -├── static/ # robots.txt, data/knowledge-graph.json (generated) -├── themes/ # blowfish (submodule v2.105.0) -├── i18n/ # ru (default) / en -├── contracts/dao/ # Engineering plane — Solidity (NOT deployed to Pages) -├── tests/hardhat/ # Hardhat tests (npx hardhat test, 9 passing) -├── src/ # v4.0 ES modules (CRDT/P2P/DAO/BCI) — retained, not bundled -├── scripts/ # content-contract + knowledge-graph generation -└── .github/ # workflows (hugo.yml is the only Pages publisher) +## Site build and publication + +`.github/workflows/hugo.yml` is the only workflow that deploys to GitHub Pages. On a push to `main` or a scheduled repository sync, it: + +1. checks out the repository and initializes the Blowfish theme; +2. installs the site generator dependencies from `scripts/`; +3. synchronizes repository and gist metadata and sanitizes generated content; +4. refreshes the knowledge graph, ontology feed, crosslinks, and curated-list catalog; +5. builds the site with Hugo and uploads the result to GitHub Pages. + +`.github/workflows/quality.yml` is the required pull request quality gate. It builds the site, checks new article metadata and internal links, and runs lint and reporting checks. It does not publish. Separate workflows handle R&D tests, end-to-end checks, security scans, and scheduled integrations. + +## Content and generated data + +- Put articles in `content/blog/` and site pages in their relevant `content/` section. +- Validate article front matter against `schema/post-metadata.schema.json` using `node scripts/validate-frontmatter.cjs `. +- Keep stable URLs when moving content by adding a Hugo `aliases` entry for each old path. +- Build-generated catalog, graph, ontology, and crosslink data should be changed through their source content or generator, not by hand. + +The content contract and authoring details are in [`CONTENT_CONTRACT.md`](CONTENT_CONTRACT.md) and [`PUBLISHING.md`](PUBLISHING.md). The architecture decision that records the publishing/R&D boundary is [`adr/0002-two-plane-architecture.md`](adr/0002-two-plane-architecture.md). + +## Local workflows + +For a site preview, install Hugo Extended 0.164.0 and Node.js 24, then run: + +```sh +git submodule update --init themes/blowfish +npm ci --prefix scripts +node scripts/sync-github.cjs +node scripts/build-knowledge-graph.cjs +node scripts/build-ontology-feed.cjs +node scripts/build-crosslinks.cjs +node scripts/build-awesome.cjs +hugo server -D ``` -### Publishing plane -- **Generator:** Hugo extended 0.164.0 + Blowfish v2.105.0 (git submodule). -- **Content:** `content/blog/`, `content/people/`, `content/domini/`, - `content/knowledge-graph/`. Legacy permalinks preserved via Hugo `aliases`. -- **Comments:** giscus (GitHub Discussions backend). **Subscription:** Buttondown. -- **Search:** Blowfish + Fuse.js (`assets/lib/fuse/fuse.min.cjs`, `index.json`). -- **Output:** static HTML in `public/` (gitignored). Deployed to GitHub Pages. - -### Engineering plane (independent) -- `src/` — ES modules. **Not imported by the static site.** Retained as R&D - substrate (CRDT/P2P/DAO/BCI adapters per `docs/adr/0001-module-layering.md`). -- `contracts/dao/` — Solidity (GovernanceToken, SoulboundToken, ProposalEngine). - Deployed separately via Hardhat (`deploy-dao.yml`, guarded by secrets). -- A Hugo failure never implies an engineering failure and vice-versa. - -## Content Contract -- New posts in `content/blog/` MUST satisfy `schema/post-metadata.schema.json`. - Enforced as a **hard gate** in `hugo.yml` via `scripts/ci-content-contract.cjs` - (added=hard, modified=soft). Invalid new post blocks the deploy. -- Knowledge Graph (`static/data/knowledge-graph.json`, JSON-LD) is emitted for - the whole corpus during the build. - -## Removed (Phase 7) -The Jekyll + esbuild stack (`_config.yml`, `Gemfile`, `_layouts/`, `_includes/`, -`_sass/`, `_posts/`, `_site/`, `js/`, `build.js`, `build-jekyll.rb`), the Jekyll -CI workflows, and the `js/refactored-bundle.js` module path are gone. Do not -reintroduce `bundle exec jekyll build` — the site is Hugo-only. - -## Notes -- `src/` dead code (`embedding-cache.js`) was removed in the cleanup phase; - `embedding-cache-service.js` remains (used by `vector-search-service.js`). -- Browser-runtime JS is provided by Blowfish's own bundle + `assets/lib/fuse`. - No hand-rolled `js/*.js` fallback exists anymore. +The engineering archive has a separate root `package.json`. Install it with `npm ci`; use `npm run lint`, `npm test`, and `npx hardhat test` for its local checks. From 4c72e1c0124d1f0186051495f8cc0696c98b7514 Mon Sep 17 00:00:00 2001 From: Domini Montessori Date: Fri, 9 Oct 2026 06:29:08 +0300 Subject: [PATCH 2/6] docs: align publishing guide with current workflows --- docs/PUBLISHING.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 3a1822f55..f330a6edc 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -4,13 +4,13 @@ How to publish content to `dominicusin.github.io` without breaking the pipeline. The site is built by Hugo (Blowfish theme) and deployed via GitHub Pages. Architecture is the **two-plane** model (see `docs/adr/0002-two-plane-architecture.md`): -- **Publishing Plane** — `content/`, `config/_default/`, `layouts/`, `static/`, `i18n/`. - Deployed to GitHub Pages by `.github/workflows/hugo.yml` (the only publisher). -- **Engineering Plane** — `contracts/dao/`, `tests/hardhat/`, `src/`. Never deployed - to Pages; tested by the DAO/Hardhat jobs. -- **Content Governance Plane** — `schema/post-metadata.schema.json`, - `scripts/ci-content-contract.cjs`, `scripts/validate-frontmatter.cjs`, - `scripts/build-knowledge-graph.cjs`. Validates and links content. +- **Website** — `content/`, `config/`, `layouts/`, `assets/`, `static/`, `i18n/`, + and the build-time generators. `.github/workflows/hugo.yml` is the only publisher. +- **Engineering archive** — `src/`, `contracts/dao/`, and their tests. It is + retained for research and is not shipped with the website. + +The article schema and scripts are part of the publishing workflow: they validate +articles and generate the graph, ontology feed, crosslinks, and curated-list data. ## Author checklist before pushing a new post @@ -41,15 +41,16 @@ Architecture is the **two-plane** model (see `docs/adr/0002-two-plane-architectu | Workflow | What | Blocks deploy? | |----------|------|----------------| -| `hugo.yml` | Build + **content-contract hard gate (new posts)** + deploy | ✅ (it is the deploy) | -| `quality.yml` | Build + content-contract (report) + jest + hardhat + lint + broken-link check | PR check (separate track) | -| `e2e.yml` | Playwright smoke + axe-core a11y | separate track | -| `performance.yml` | Lighthouse budget (LCP≤2.5s, CLS≤0.1) | separate track (fails job, not site) | -| `security.yml` | npm audit + Trivy + Semgrep | separate track | +| `hugo.yml` | Generate site data, build Hugo, and publish to GitHub Pages | ✅ (it is the deploy) | +| `quality.yml` | Required PR gate: Hugo build, content contract, lint, internal-link checks, and report-only audits | No; blocks merge when required checks fail | +| `test-rnd.yml` | Jest and Hardhat checks for changes to the engineering archive | No; separate from the publishing gate | +| `e2e.yml` | Playwright end-to-end checks | No; separate check | +| `performance.yml` | Lighthouse performance audit | No; separate check | +| `security.yml` | npm audit, Trivy, and Semgrep scans | No; separate check | ## Knowledge Graph -Every build regenerates `static/data/knowledge-graph.json` (JSON-LD) from the +Every deployment regenerates `static/data/knowledge-graph.json` (JSON-LD) from the published content. It is rendered by the `/knowledge-graph/` page widget. Concepts come from post `tags`/taxonomy; to make a post appear in the graph, give it meaningful `tags`. From 8d252784f47c9cc9727a23c701748d6a925b8766 Mon Sep 17 00:00:00 2001 From: Domini Montessori Date: Fri, 9 Oct 2026 06:30:11 +0300 Subject: [PATCH 3/6] docs: align contributor guides with Hugo workflows --- CONTRIBUTING.md | 136 ++++------------ docs/CONTRIBUTING.md | 358 ++++--------------------------------------- 2 files changed, 56 insertions(+), 438 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5bb3aca59..a2fb6bcf4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,121 +1,41 @@ -# Contributing to dominicusin.github.io +# Contributing -## Quick Start +This repository publishes a Hugo site and retains a separate engineering archive. See the [README](README.md) for the project map and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the build boundary. -```bash -# 1. Clone -git clone https://github.com/dominicusin/dominicusin.github.io.git -cd dominicusin.github.io +## Site content -# 2. Install deps -npm install +1. Add articles under `content/blog/` and pages under the appropriate `content/` section. +2. Keep front matter aligned with `schema/post-metadata.schema.json` and preserve old URLs with Hugo aliases when renaming content. +3. Validate a new article with `node scripts/validate-frontmatter.cjs content/blog/.md`. +4. Follow the author checklist in [docs/PUBLISHING.md](docs/PUBLISHING.md). -# 3. Build -npm run build +For a local site preview, install Node.js 24 and Hugo Extended 0.164.0, then initialize the theme and generators: -# 4. Test -npm test - -# 5. Serve locally -npm run start -``` - -## Project Structure - -``` -├── assets/ -│ ├── css/ -│ │ ├── neo.css # Neo design system (main CSS) -│ │ └── critical/ # Above-fold critical CSS -│ └── js/ -│ └── custom.js # All client-side JS -├── content/ # Hugo content (blog, repos, gists, awesome) -│ ├── blog/ -│ ├── repositories/ -│ ├── gists/ -│ └── awesome/ -├── data/ # Hugo data files (JSON) -├── layouts/ -│ ├── _default/ # Default templates -│ ├── partials/ # Reusable partials -│ │ ├── neo-head.html # with SEO + performance -│ │ ├── neo-store.html # Centralized localStorage -│ │ ├── content-graph.html # Related posts + tags -│ │ └── neo-subscribe.html # Newsletter + share -│ ├── shortcodes/ # Hugo shortcodes -│ └── analytics/ # Dashboard templates -├── static/ # Static files (served as-is) -│ ├── sw.js # Service Worker -│ ├── manifest.webmanifest # PWA manifest -│ └── .well-known/security.txt -├── scripts/ # Build scripts -└── tests/ # Test suites - ├── unit/ # Unit tests - ├── a11y/ # Accessibility - └── e2e/ # End-to-end +```sh +git submodule update --init themes/blowfish +npm ci --prefix scripts +node scripts/sync-github.cjs +node scripts/build-knowledge-graph.cjs +node scripts/build-ontology-feed.cjs +node scripts/build-crosslinks.cjs +node scripts/build-awesome.cjs +hugo server -D ``` -## Development Workflow - -### Branch Naming -- `feat/waveXX-feature-name` — new features -- `fix/issue-description` — bug fixes -- `chore/task-name` — maintenance - -### Pull Request Process -1. Create feature branch from `main` -2. Make changes, verify locally: `npm run build && npm test` -3. Push and create PR -4. Quality CI must pass (build → validate → test → link-check) -5. Merge via `gh pr merge --squash --admin` +## Engineering archive -### Code Style -- **CSS**: Use Neo design tokens (`--bg`, `--text`, `--accent`) -- **JS**: Use IIFE pattern, avoid global scope pollution -- **HTML**: Use semantic elements, ARIA labels +`src/` and `contracts/dao/` are retained research projects and are not included in the published site. Install the root Node dependencies to work on them: -## Testing - -```bash -# All tests +```sh +npm ci +npm run lint npm test - -# Unit tests only -npx jest tests/unit - -# With coverage -npm run test:coverage +npx hardhat test ``` -## Design System - -### Themes -Switch via `data-theme` attribute on ``: -- `dark` (default) -- `light` -- `solar` -- `mono` -- `dracula` - -### Accents -Switch via `data-accent` attribute: -- `teal` (default) -- `violet` -- `amber` -- `emerald` -- `rose` - -### Key Classes -- `.neo-card` — content cards -- `.neo-row` — list items -- `.neo-post` — article wrapper -- `.neo-wrap` — content container -- `.neo-sec-head` — section header - -## Architecture Decisions +## Pull requests -1. **No backend** — static site on GitHub Pages -2. **localStorage** — centralized in `neoStore` (neo-store-v1) -3. **Critical CSS** — inline above-fold, async rest -4. **Search** — build-time index, client-side fuzzy match -5. **Analytics** — local only, no external tracking +- Open changes against `main` and describe the user-visible or maintenance outcome. +- The required **Quality CI** check builds Hugo and checks content metadata, lint, and internal links. Playwright and security workflows run separately. +- Changes to the engineering archive also trigger the R&D workflow. +- Keep generated build output, dependency folders, and Hugo caches out of commits. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index e08b6b6c8..3c9b4c619 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,343 +1,41 @@ -# Руководство по внесению изменений (Contributing Guide) +# Как внести изменения -## 📋 Содержание +В репозитории публикуется сайт на Hugo и хранится отдельный инженерный архив. Карту проекта и команды см. в [README](../README.md), устройство сборки — в [описании архитектуры](ARCHITECTURE.md). -1. [Введение](#введение) -2. [Требования к разработке](#требования-к-разработке) -3. [Структура проекта](#структура-проекта) -4. [Процесс разработки](#процесс-разработки) -5. [Стандарты кода](#стандарты-кода) -6. [Тестирование](#тестирование) -7. [Документирование](#документирование) -8. [Pull Request процесс](#pull-request-процесс) +## Публикация материалов ---- +1. Статьи размещаются в `content/blog/`, страницы — в подходящем разделе `content/`. +2. Новые статьи должны соответствовать `schema/post-metadata.schema.json`. При смене URL добавляйте Hugo `aliases`, чтобы сохранить старые ссылки. +3. Проверка метаданных статьи: `node scripts/validate-frontmatter.cjs content/blog/<файл>.md`. +4. Локальный просмотр и публикация описаны в [руководстве по публикации](PUBLISHING.md). -## Введение +Для локального просмотра нужны Node.js 24 и Hugo Extended 0.164.0: -Спасибо за интерес к проекту Engineering Blog! Это руководство поможет вам внести свой вклад в развитие проекта. - -### Типы взносов - -- **Багфиксы**: Исправление ошибок -- **Новые функции**: Добавление новых возможностей -- **Документация**: Улучшение документации -- **Оптимизация**: Улучшение производительности -- **Рефакторинг**: Улучшение структуры кода - ---- - -## Требования к разработке - -### Необходимое ПО - -```bash -Node.js >= 22.0.0 -npm >= 9.0.0 -Ruby >= 3.0.0 -Bundler >= 2.0.0 -Git -``` - -### Установка зависимостей - -```bash -# Install Node.js dependencies -npm install - -# Install Ruby dependencies -bundle install -``` - ---- - -## Структура проекта - -``` -/workspace -├── src/ # Исходный код JavaScript -│ ├── config/ # Конфигурация -│ ├── core/ # Базовые модули -│ ├── modules/ # Функциональные модули -│ ├── services/ # Сервисы (Analytics, PWA) -│ ├── utils/ # Утилиты -│ └── index.js # Точка входа -├── tests/ # Тесты -│ ├── unit/ # Unit тесты -│ ├── integration/ # Integration тесты -│ └── test-utils.js # Утилиты для тестов -├── docs/ # Документация -├── _layouts/ # Jekyll шаблоны -├── _includes/ # Jekyll включает -└── js/ # Скомпилированные файлы -``` - ---- - -## Процесс разработки - -### 1. Форк и клонирование - -```bash -git clone https://github.com/YOUR_USERNAME/engineering-blog.git -cd engineering-blog -``` - -### 2. Создание ветки - -```bash -# Для новой функции -git checkout -b feature/your-feature-name - -# Для багфикса -git checkout -b fix/issue-number-description +```sh +git submodule update --init themes/blowfish +npm ci --prefix scripts +node scripts/sync-github.cjs +node scripts/build-knowledge-graph.cjs +node scripts/build-ontology-feed.cjs +node scripts/build-crosslinks.cjs +node scripts/build-awesome.cjs +hugo server -D ``` -### 3. Разработка +## Инженерный архив -```bash -# Запуск в режиме разработки -npm run dev +Каталоги `src/` и `contracts/dao/` сохранены как исследовательские проекты и не попадают на сайт. Для работы с ними установите зависимости корневого `package.json`: -# Запуск тестов -npm run test - -# Линтинг +```sh +npm ci npm run lint +npm test +npx hardhat test ``` -### 4. Коммиты - -Используйте [Conventional Commits](https://www.conventionalcommits.org/): - -```bash -# Новая функция -git commit -m "feat: add dark mode support" - -# Багфикс -git commit -m "fix: correct theme toggle behavior" - -# Документация -git commit -m "docs: update README with installation steps" - -# Рефакторинг -git commit -m "refactor: simplify module loading logic" -``` - ---- - -## Стандарты кода - -### JavaScript Style Guide - -```javascript -// ✅ ПРАВИЛЬНО - -// Использовать const/let вместо var -const MAX_RETRIES = 3; -let count = 0; - -// Именованные импорты -import { debounce, throttle } from './utils/helpers.js'; - -// JSDoc комментарии -/** - * Debounce function execution - * @param {Function} func - Function to debounce - * @param {number} wait - Wait time in ms - * @returns {Function} Debounced function - */ -export function debounce(func, wait = 300) { - let timeout; - return (...args) => { - clearTimeout(timeout); - timeout = setTimeout(() => func(...args), wait); - }; -} - -// Arrow functions для методов -const handler = () => { - // implementation -}; - -// Template literals -const message = `Hello, ${name}!`; - -// Destructuring -const { theme, locale } = config; -``` - -```javascript -// ❌ НЕПРАВИЛЬНО - -var count = 0; // Используйте const/let -import * as helpers from './utils/helpers.js'; // Избегайте namespace imports - -function oldStyle() { // Используйте arrow functions - return 'test'; -} - -var str = 'Hello, ' + name + '!'; // Используйте template literals -``` - -### Именование - -- **Классы**: PascalCase (`ThemeManager`, `SearchEngine`) -- **Функции/переменные**: camelCase (`debounce`, `currentTheme`) -- **Константы**: UPPER_SNAKE_CASE (`MAX_RETRIES`, `DEFAULT_CONFIG`) -- **Файлы**: kebab-case (`theme-manager.js`, `search-engine.test.js`) - ---- - -## Тестирование - -### Написание тестов - -```javascript -// tests/unit/example.test.js -import { describe, it, expect, beforeEach } from '../test-utils.js'; -import { MyModule } from '../../src/modules/my-module.js'; - -describe('MyModule', () => { - let module; - - beforeEach(() => { - module = new MyModule(); - }); - - it('should initialize correctly', () => { - expect(module).toBeInstanceOf(MyModule); - }); - - it('should handle edge cases', () => { - expect(() => module.process(null)).not.toThrow(); - }); -}); -``` - -### Запуск тестов - -```bash -# Все тесты -npm run test - -# Watch mode -npm run test:watch - -# Coverage -npm run test:coverage -``` - -### Требования к покрытию - -- Utils: 100% -- Core modules: 95%+ -- Functional modules: 90%+ -- Integration tests: Critical paths 100% - ---- - -## Документирование - -### JSDoc - -Все публичные API должны иметь JSDoc комментарии: - -```javascript -/** - * Theme Manager - Handles theme switching and persistence - * @extends EventEmitter - */ -export class ThemeManager { - /** - * Create ThemeManager instance - * @param {Object} options - Configuration options - * @param {string} options.container - CSS selector for container - * @param {string} options.defaultTheme - Default theme ('light'|'dark'|'auto') - */ - constructor(options = {}) { - // implementation - } - - /** - * Set theme - * @param {string} theme - Theme to set - * @fires ThemeManager#themeChanged - * @returns {void} - */ - setTheme(theme) { - // implementation - } -} -``` - -### Обновление документации - -При добавлении новых функций обновляйте: - -1. `README.md` - общее описание -2. `docs/ARCHITECTURE.md` - архитектурные изменения -3. `docs/API.md` - изменения API -4. JSDoc комментарии в коде - ---- - -## Pull Request процесс - -### Чеклист перед PR - -- [ ] Код следует стандартам проекта -- [ ] Все тесты проходят (`npm run test`) -- [ ] Линтер не выдаёт ошибок (`npm run lint`) -- [ ] Добавлены тесты для новых функций -- [ ] Обновлена документация -- [ ] Commit messages следуют Conventional Commits - -### Создание PR - -1. Создайте форк репозитория -2. Создайте feature ветку -3. Внесите изменения -4. Убедитесь, что все тесты проходят -5. Создайте Pull Request с описанием изменений - -### Описание PR - -```markdown -## Описание -Краткое описание изменений - -## Тип изменений -- [ ] Багфикс -- [ ] Новая функция -- [ ] Breaking change -- [ ] Документация -- [ ] Рефакторинг - -## Тестирование -Опишите, как вы тестировали изменения - -## Чеклист -- [ ] Тесты добавлены/обновлены -- [ ] Документация обновлена -- [ ] Следую стандартам кода -``` - -### Review процесс - -1. Автоматические проверки (CI/CD) -2. Code review от maintainers -3. Исправление замечаний -4. Merge после approval - ---- - -## Контакты - -- **Issues**: GitHub Issues -- **Discussions**: GitHub Discussions -- **Email**: dominicusin@example.com - ---- +## Pull request -*Спасибо за ваш вклад!* 🎉 +- Создавайте PR в `main` и коротко описывайте результат. +- Обязательная проверка **Quality CI** собирает Hugo-сайт и проверяет метаданные, lint и внутренние ссылки. +- Для изменений инженерного архива отдельно запускаются R&D-проверки; Playwright и сканеры безопасности также идут отдельными workflow. +- Не добавляйте в коммиты сгенерированную сборку, `node_modules` и кэш Hugo. From 312638b2056ac8f94e7692932fd1c8d5d6b55597 Mon Sep 17 00:00:00 2001 From: Domini Montessori Date: Fri, 9 Oct 2026 06:32:26 +0300 Subject: [PATCH 4/6] docs: clarify publishing workflow roles --- docs/PUBLISHING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index f330a6edc..f57c3da6c 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -39,14 +39,14 @@ articles and generate the graph, ontology feed, crosslinks, and curated-list dat ## What the CI enforces -| Workflow | What | Blocks deploy? | +| Workflow | What | Release role | |----------|------|----------------| -| `hugo.yml` | Generate site data, build Hugo, and publish to GitHub Pages | ✅ (it is the deploy) | -| `quality.yml` | Required PR gate: Hugo build, content contract, lint, internal-link checks, and report-only audits | No; blocks merge when required checks fail | -| `test-rnd.yml` | Jest and Hardhat checks for changes to the engineering archive | No; separate from the publishing gate | -| `e2e.yml` | Playwright end-to-end checks | No; separate check | -| `performance.yml` | Lighthouse performance audit | No; separate check | -| `security.yml` | npm audit, Trivy, and Semgrep scans | No; separate check | +| `hugo.yml` | Generate site data, build Hugo, and publish to GitHub Pages | Builds and publishes the site | +| `quality.yml` | Hugo build, content contract, lint, internal-link checks, and report-only audits | Required PR check; blocks merge on failure | +| `test-rnd.yml` | Jest and Hardhat checks for changes to the engineering archive | Separate R&D check | +| `e2e.yml` | Playwright end-to-end checks | Separate check | +| `performance.yml` | Lighthouse performance audit | Separate check | +| `security.yml` | npm audit, Trivy, and Semgrep scans | Separate check | ## Knowledge Graph From f0673c26102ab5beeb33740aa643192323943355 Mon Sep 17 00:00:00 2001 From: Domini Montessori Date: Fri, 9 Oct 2026 06:37:06 +0300 Subject: [PATCH 5/6] docs: state R&D workflow status accurately --- CONTRIBUTING.md | 2 +- README.md | 4 ++-- docs/ARCHITECTURE.md | 4 ++-- docs/CONTRIBUTING.md | 2 +- docs/PUBLISHING.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2fb6bcf4..2af5961da 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,5 +37,5 @@ npx hardhat test - Open changes against `main` and describe the user-visible or maintenance outcome. - The required **Quality CI** check builds Hugo and checks content metadata, lint, and internal links. Playwright and security workflows run separately. -- Changes to the engineering archive also trigger the R&D workflow. +- The R&D test workflow is currently disabled because its DAO test job fails on `main`; archive test commands remain available locally. - Keep generated build output, dependency folders, and Hugo caches out of commits. diff --git a/README.md b/README.md index 6ef6f75c6..45205806f 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ New articles belong in `content/blog/`. Keep front matter aligned with the conte ## Project checks -The required pull request gate is the **Quality CI** workflow. It installs the root Node dependencies, builds Hugo, checks content and internal links, and runs the repository lint step. The separate R&D workflow handles the retained JavaScript and Solidity suites for changes to those areas. +The required pull request gate is **Quality CI**. It installs the root Node dependencies, builds Hugo, checks content and internal links, and runs the repository lint step. The Playwright workflow runs separately. The R&D test workflow is currently disabled in GitHub Actions because its DAO test job fails on `main`; its suites are not part of the required pull request gate. Useful local commands: @@ -67,7 +67,7 @@ npm test npx hardhat test ``` -These commands cover the engineering archive. The site build uses the nested tooling dependencies installed with `npm ci --prefix scripts`. +These commands are available for local work on the engineering archive. The site build uses the nested tooling dependencies installed with `npm ci --prefix scripts`. ## License diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0f24b10da..bf700d275 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -16,7 +16,7 @@ src/ contracts/ tests/ Retained engineering experiments and test suites .github/workflows/ Build, quality, security, and integration automation ``` -`content/`, `config/`, `layouts/`, theme overrides, and generated data form the publishing path. `src/` and `contracts/dao/` are an independent, retained R&D archive; Hugo does not bundle them into the website. Their tests run in a separate workflow. +`content/`, `config/`, `layouts/`, theme overrides, and generated data form the publishing path. `src/` and `contracts/dao/` are an independent, retained R&D archive; Hugo does not bundle them into the website. The R&D test workflow is currently disabled in GitHub Actions because the DAO test job fails on `main`. ## Site build and publication @@ -28,7 +28,7 @@ src/ contracts/ tests/ Retained engineering experiments and test suites 4. refreshes the knowledge graph, ontology feed, crosslinks, and curated-list catalog; 5. builds the site with Hugo and uploads the result to GitHub Pages. -`.github/workflows/quality.yml` is the required pull request quality gate. It builds the site, checks new article metadata and internal links, and runs lint and reporting checks. It does not publish. Separate workflows handle R&D tests, end-to-end checks, security scans, and scheduled integrations. +`.github/workflows/quality.yml` is the required pull request quality gate. It builds the site, checks new article metadata and internal links, and runs lint and reporting checks. It does not publish. Separate active workflows handle end-to-end checks, security scans, and scheduled integrations. The R&D test workflow is disabled and does not validate pull requests. ## Content and generated data diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3c9b4c619..42ab95bac 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -37,5 +37,5 @@ npx hardhat test - Создавайте PR в `main` и коротко описывайте результат. - Обязательная проверка **Quality CI** собирает Hugo-сайт и проверяет метаданные, lint и внутренние ссылки. -- Для изменений инженерного архива отдельно запускаются R&D-проверки; Playwright и сканеры безопасности также идут отдельными workflow. +- R&D workflow сейчас отключён: проверка DAO-тестов падает на `main`. Команды для локальных проверок архива остаются доступными; Playwright и сканеры безопасности запускаются отдельными workflow. - Не добавляйте в коммиты сгенерированную сборку, `node_modules` и кэш Hugo. diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index f57c3da6c..bb63550bd 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -43,7 +43,7 @@ articles and generate the graph, ontology feed, crosslinks, and curated-list dat |----------|------|----------------| | `hugo.yml` | Generate site data, build Hugo, and publish to GitHub Pages | Builds and publishes the site | | `quality.yml` | Hugo build, content contract, lint, internal-link checks, and report-only audits | Required PR check; blocks merge on failure | -| `test-rnd.yml` | Jest and Hardhat checks for changes to the engineering archive | Separate R&D check | +| `test-rnd.yml` | Jest and Hardhat checks for the engineering archive | Disabled in GitHub Actions; its DAO job currently fails on `main` | | `e2e.yml` | Playwright end-to-end checks | Separate check | | `performance.yml` | Lighthouse performance audit | Separate check | | `security.yml` | npm audit, Trivy, and Semgrep scans | Separate check | From fc75a3e33df588a4b4c2af0b029b2d41f12d66c5 Mon Sep 17 00:00:00 2001 From: Domini Montessori Date: Fri, 9 Oct 2026 06:37:22 +0300 Subject: [PATCH 6/6] docs: mark disabled R&D workflow in source --- .github/workflows/test-rnd.yml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/.github/workflows/test-rnd.yml b/.github/workflows/test-rnd.yml index 820e7a037..bb7a6d89a 100644 --- a/.github/workflows/test-rnd.yml +++ b/.github/workflows/test-rnd.yml @@ -1,11 +1,12 @@ name: 🧪 R&D Tests -# Isolated R&D test gate (TASK-C2 / T89). Runs the experimental-plane suites -# (src/ jest + contracts/dao hardhat) separately from the production Hugo build -# so a flaky R&D test cannot block the GitHub Pages deploy. Triggered on any -# change touching the R&D surface. Not a required status check for merge -# (the required checks are "test" + "build" in hugo.yml), but it surfaces R&D -# regressions on every relevant push/PR. +# STATUS: disabled manually in GitHub Actions after the DAO test job failed on +# main (last updated 2026-08-25). Do not describe this workflow as an active +# check. Re-enable it after repairing and verifying the DAO test suite. +# +# When enabled, this isolates the experimental-plane suites (src/ Jest and +# contracts/dao Hardhat) from the production Hugo build, so an R&D failure does +# not block the Pages deploy. The job is not a required status check for merge. on: push: