🛡️ Secure Contribution Guidelines
🎯 Building Democratic Transparency Through Collaborative Excellence
📋 Document Owner: CEO | 📄 Version: 1.0 | 📅 Last Updated: 2026-02-20 (UTC)
🔄 Review Cycle: Quarterly | ⏰ Next Review: 2026-05-20
🏢 Owner: Hack23 AB (Org.nr 5595347807) | 🏷️ Classification: Public
This contributing guide establishes secure contribution procedures for Riksdagsmonitor, implementing Secure Development Policy and Change Management from Hack23 AB's ISMS framework.
We believe in security through transparency and continuous improvement, welcoming contributions that enhance democratic transparency while maintaining our high security standards.
— James Pether Sörling, CEO/Founder
Hi there! We're thrilled that you'd like to contribute to Riksdagsmonitor. Your help is essential for keeping it great.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
If you have suggestions for how this project could be improved, or want to report a bug, open an issue! We'd love all and any contributions. If you have questions, too, we'd love to hear them.
We'd also love PRs. If you're thinking of a large PR, we advise opening up an issue first to talk about it, though! Look at the links below if you're not sure how to open a PR.
- Fork and clone the repository.
- Install dependencies:
npm install - Make sure the tests pass on your machine:
npm test - Create a new branch:
git checkout -b my-branch-name - Make your change, add tests, and make sure the tests still pass.
- Validate HTML:
npm run htmlhint - Push to your fork and submit a pull request.
- Pat yourself on the back and wait for your pull request to be reviewed and merged.
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
- Follow the existing code style (HTML5 semantic markup, CSS custom properties, mobile-first design)
- Write and update tests (Vitest for unit tests, Cypress for E2E)
- Keep your changes as focused as possible
- Ensure WCAG 2.1 AA accessibility compliance
- Validate HTML with HTMLHint before submitting
- Write a good commit message
Work in Progress pull requests are also welcome to get feedback early on.
| Directory | Purpose |
|---|---|
*.html |
Multi-language index pages (14 languages) |
styles.css |
Cyberpunk theme design system |
js/ |
Dashboard JavaScript modules (Chart.js, D3.js, Mermaid init) |
dashboard/ |
Interactive intelligence dashboards |
news/ |
Rendered political news articles ($DATE-$SUB-$LANG.html) |
analysis/daily/$DATE/$SUB/ |
Per-day analysis artifacts consumed by the aggregator |
analysis/methodologies/ |
Editorial method files (source of truth for how analysis is done) |
analysis/templates/ |
Output section templates (source of truth for what goes in an article) |
scripts/aggregate-analysis.ts |
Concatenates daily artifacts → canonical article.md + manifest |
scripts/render-articles.ts + scripts/render-lib/ |
Markdown → sanitised HTML (unified / remark / rehype) |
scripts/ |
Other build, generation, and utility scripts |
tests/ |
Vitest unit tests |
cypress/ |
Cypress E2E tests |
cia-data/ |
CIA platform data exports |
The legacy content-generator approach (generate-news-enhanced, article-template) has been removed. To add a new news type:
- Pick a subfolder slug (e.g.
interpellations-deep) — this becomesanalysis/daily/$DATE/$SUB/. - Register it in the aggregator section-order config under
analysis/templates/— this determines narrative flow without touching TypeScript. - Copy an existing per-type workflow
.mdfrom.github/workflows/news-*.md(e.g.news-propositions.md) and adapt:- analysis phase: the specific MCP queries the new type needs
- analysis gate: the per-type 9-artifact or 14-artifact list (see
.github/prompts/05-analysis-gate.md) - front-matter: schedule, subfolder slug, description
- Compile with
gh aw compileto produce the matching.lock.yml. - Never hand-write localised HTML. The per-type workflow only produces
$DATE-$SUB-en.html+$DATE-$SUB-sv.html; the rest are the sole responsibility of thenews-translateworkflow.
See WORKFLOWS.md §5 for the full agentic-workflow structure, and ARCHITECTURE.md §"News Generation Pipeline Architecture" for the aggregator/renderer contract.
All PRs must pass these quality gates before merge:
| Check | Tool | Purpose |
|---|---|---|
| HTML Validation | HTMLHint | Standards compliance |
| Link Checking | Linkinator | Verify internal/external links |
| JavaScript Linting | ESLint | Code quality |
| Unit Tests | Vitest | Functionality verification |
| Security Scanning | CodeQL, Dependabot | Vulnerability detection |
| Secret Scanning | GitHub | Credential leak prevention |
Riksdagsmonitor supports 14 languages. When making content changes:
- Update all affected language files
- Use
langattribute on<html>tags - Support RTL for Arabic (
index_ar.html) and Hebrew (index_he.html) - Include
hreflangtags for SEO - See TRANSLATION_GUIDE.md for vocabulary reference
This project has 14 specialized GitHub Copilot agents to assist development:
- security-architect — Security architecture and ISMS compliance
- documentation-architect — C4 models and technical documentation
- quality-engineer — HTML/CSS validation and accessibility
- frontend-specialist — Responsive design and multi-language support
- intelligence-operative — Political data analysis
- content-generator — Automated news generation
Learn more in AGENTS.md.
- 🛠️ Secure Development Policy — Development security standards
- 📝 Change Management — Change control procedures
- 🔐 Information Security Policy — Overall security governance
- 🔍 Vulnerability Management — Security testing and remediation
- 📋 README — Project overview and classification
- 🔐 Security Policy — Vulnerability reporting
- 📜 Code of Conduct — Community standards
- 🏗️ Architecture — System architecture
- 🔧 Workflows — CI/CD documentation
- 🧪 Testing — Test strategy and coverage
📋 Document Control:
✅ Approved by: James Pether Sörling, CEO
📤 Distribution: Public
🏷️ Classification:
📅 Effective Date: 2026-02-20
⏰ Next Review: 2026-05-20
🎯 Framework Compliance: 
