🤝 Contributing to EU Parliament Monitor

Code · Tests · Docs · Translations · Political Intelligence · Security
🇪🇺 Civic-tech for European democracy · 🛡️ Security-by-design · 🌍 14 languages · ♿ WCAG 2.1 AA

📋 Document Owner: CEO | 📄 Version: 1.2 | 📅 Last Updated: 2026-04-27 (UTC) 🔄 Review Cycle: Quarterly | ⏰ Next Review: 2026-07-27 | 🏷️ Classification: Public

Thank you for your interest in contributing to EU Parliament Monitor — the open-source European Parliament political-intelligence platform that publishes AI-generated, evidence-based analysis in 14 languages every day. We welcome contributions from developers, journalists, translators, political scientists, OSINT analysts, accessibility advocates, and security researchers.

💜 Code of Conduct

This project adheres to the Contributor Covenant 2.1. By participating, you agree to maintain a respectful and inclusive environment. Report unacceptable behaviour to conduct@hack23.com.

👥 Who Should Contribute

🎭 Role	🎯 What you can do
👨‍💻 Developers	TypeScript aggregator, MCP integrations, GitHub Actions, accessibility, performance
📰 Journalists	Editorial style review, political analysis quality, source attribution discipline
🌐 Translators	Improve any of the 14 languages (EN, SV, DA, NO, FI, DE, FR, ES, NL, AR, HE, JA, KO, ZH)
🧠 Political scientists / OSINT analysts	Methodologies under `analysis/methodologies/`, threat-framework refinement, ACH/SWOT/PESTLE rigor
♿ Accessibility advocates	WCAG 2.1 AA audits, RTL improvements (Arabic, Hebrew), screen-reader testing
🛡️ Security researchers	Responsible disclosure via SECURITY.md — see also SECURITY_ARCHITECTURE.md and THREAT_MODEL.md
📚 Doc authors	Architecture docs (ARCHITECTURE.md), C4 diagrams, ADRs, runbooks

🚀 Getting Started

📋 Prerequisites

🟢 Node.js ≥ 25 (the platform runtime — see package.json engines.node)
📦 npm ≥ 10 (ships with Node.js 25)
🔧 Git

Setup

Fork the repository

Clone your fork:

git clone https://github.com/YOUR_USERNAME/euparliamentmonitor.git
cd euparliamentmonitor

Install dependencies:
```
npm install
```

Create a branch for your changes:

git checkout -b feature/your-feature-name

🛠️ Development Workflow

▶️ Running Locally

# Render an article from analysis artifacts (manual testing)
npm run generate-article -- --run analysis/daily/2025-01-01/week-ahead

# Generate index pages
npm run generate-news-indexes

# Generate sitemap
npm run generate-sitemap

# Serve locally
npm run serve

Code Quality Checks

Before committing, run these checks:

# Lint your code
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format your code
npm run format

# Check formatting
npm run format:check

# Validate HTML
npm run htmlhint

✅ Code Quality Requirements

All contributions must meet these quality standards:

Testing Requirements

All contributions must include appropriate tests:

Unit & Integration Tests (Vitest)

Unit Tests: Write unit tests for new functions and modules
Integration Tests: Add integration tests for new workflows
Coverage: Maintain ≥80% line coverage, ≥75% branch coverage
Test Quality: Follow AAA pattern (Arrange, Act, Assert)
No Flaky Tests: Ensure tests are deterministic and reliable

# Run unit & integration tests
npm test

# Check coverage
npm run test:coverage

# Run specific test file
npx vitest test/unit/your-test.test.js

End-to-End Tests (Playwright)

E2E Tests: Add E2E tests for user-facing features
Accessibility: Ensure WCAG 2.1 AA compliance
Responsive Design: Test on mobile and desktop viewports
Cross-Browser: Tests run on Chromium, Firefox, and WebKit

# Run E2E tests
npm run test:e2e

# Run with UI (interactive debugging)
npm run test:e2e:ui

# Run in headed mode (see browser)
npm run test:e2e:headed

When to add E2E tests:

New user-facing features (navigation, forms, etc.)
Changes to page structure or layout
Multi-language functionality changes
Accessibility improvements
Responsive design changes

Required for all code changes:

New functions must have unit tests
New features must have integration tests
User-facing features should have E2E tests
All tests must pass before PR submission
Coverage thresholds must be met

ESLint

Zero errors required (warnings are acceptable for false positives)
All functions must have complete JSDoc documentation
Code complexity must be ≤15 (cognitive complexity)
No security vulnerabilities (eval, unsafe regex, etc.)

Prettier

All JavaScript files must be formatted with Prettier
Use the project's .prettierrc.json configuration
100 character line width
Single quotes for strings

JSDoc Documentation

All exported functions must include:

/**
 * Brief function description
 * @param {type} paramName - Parameter description
 * @returns {type} Return value description
 */

Security

Security Architecture: All security changes must align with the Security Architecture and ISMS Secure Development Policy.

Security Requirements:

Never commit secrets or API keys
Use === instead of ==
Avoid eval() and new Function()
Validate all user inputs (see Security Controls)
Prevent XSS vulnerabilities (multi-layer defense: validation, sanitization, encoding, CSP)
No SQL injection risks (static site, no databases)
Test security-critical paths (≥95% coverage)
Follow threat model mitigations (see Threat Model)

Security Review Checklist:

Input validation implemented for all external data
HTML sanitization applied (script tags, event handlers removed)
Output encoding used (HTML entity encoding)
No new dependencies without security scanning (npm audit)
Security tests added for new attack surfaces
Documentation updated (SECURITY_ARCHITECTURE.md if applicable)
Threat model reviewed for new threats

Security Testing:

# Run security audit
npm audit

# Run security-focused tests
npm run test:unit -- --grep="security|xss|injection|sanitize"

# Check for vulnerable dependencies
npm audit --audit-level=moderate

Pre-commit Hooks

The project uses Husky and lint-staged to automatically:

Run ESLint with auto-fix on staged JavaScript files
Format staged files with Prettier
Validate HTML files with htmlhint
Run affected tests (if configured)

These hooks run automatically on git commit. To bypass (not recommended):

git commit --no-verify

📝 Commit Guidelines

Commit Message Format

Use conventional commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests (use this for test-related commits!)
chore: Maintenance tasks
ci: CI/CD changes

Examples

git commit -m "feat(news): add breaking news article type"
git commit -m "fix(mcp): handle connection timeout gracefully"
git commit -m "docs: update code standards documentation"
git commit -m "refactor(generator): reduce complexity in generateWeekAhead"
git commit -m "test: add unit tests for article template"
git commit -m "test: increase coverage for MCP client"

🔀 Pull Request Process

Before Submitting

Run all quality checks:

npm run lint
npm run format:check
npm run htmlhint
npm test
npm run test:e2e

Check test coverage:

npm run test:coverage
# Ensure coverage thresholds are met
# Lines: ≥80%, Branches: ≥75%

Test your changes:

# Render an article from analysis (if applicable)
npm run generate-article -- --run analysis/daily/YYYY-MM-DD/week-ahead

# Verify output
npm run generate-news-indexes
npm run generate-sitemap

# Test E2E (if UI changes)
npm run test:e2e:headed

Update documentation if you've:
- Added new features
- Changed APIs or interfaces
- Modified configuration
- Added new test files (update test/README.md or e2e/README.md)

PR Checklist

PR Description

Include in your PR description:

What: Brief description of the change
Why: Reason for the change
How: Technical approach used
Testing: How you tested the changes
Screenshots: For UI changes

CI/CD Checks

Your PR must pass these automated checks:

✅ ESLint (zero errors)
✅ Prettier formatting
✅ HTML validation
✅ JavaScript syntax check
✅ Unit tests
✅ Integration tests
✅ E2E tests (runs daily and on PRs)
✅ Coverage thresholds (80%/75%)
✅ Security audit (npm audit)
✅ Functional tests

Review Process

Automated checks must pass
At least one maintainer review required
All review comments must be addressed
PR will be merged by a maintainer

📂 Project Structure

euparliamentmonitor/
├── .github/              # GitHub workflows and configuration
│   ├── workflows/        # CI/CD workflows + agentic workflows (news-*.md)
│   └── agents/          # Custom GitHub Copilot agents
├── scripts/             # Compiled JavaScript from src/
│   ├── aggregator/      # Article generation aggregator
│   ├── generators/      # Index & sitemap generators
│   └── mcp/             # MCP clients
├── src/                 # TypeScript source
│   ├── aggregator/      # Analysis aggregation + article rendering
│   ├── generators/      # Sitemap, indexes, political intelligence
│   ├── mcp/             # MCP client implementations
│   ├── utils/           # Utilities (file, metadata, sanitize)
│   ├── types/           # TypeScript type definitions
│   └── constants/       # Configuration constants
├── test/                # Unit & integration tests
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   ├── fixtures/        # Test data
│   └── helpers/         # Test utilities
├── e2e/                 # End-to-end tests
│   ├── tests/           # E2E test files
│   └── README.md        # E2E testing guide
├── news/                # Generated news articles
├── docs/                # Documentation
│   └── CODE_STANDARDS.md # Code quality standards
├── .husky/              # Pre-commit hooks
├── eslint.config.js     # ESLint configuration
├── .prettierrc.json     # Prettier configuration
├── playwright.config.js # Playwright E2E configuration
└── package.json         # Dependencies and scripts

🤖 Custom Agents

EU Parliament Monitor ships with a layered agent catalog under .github/agents/ — product-domain agents that own the news critical path, plus infrastructure agents that maintain workflow and CI hygiene. See .github/agents/README.md for the full directory and the .github/skills/ and .github/prompts/ libraries that they share.

🎭 Product-domain agents (own the news critical path)

Agent	Role
🕵️ `@intelligence-operative`	Senior political-intelligence analyst — applies ACH, SWOT, PESTLE, OSINT tradecraft, threat framework. Owns Stage-B analysis artifacts.
📰 `@news-journalist`	The Economist-style EP reporting in 14 languages. Authors editorial prose only when analysis artifacts are signed off.
🔄 `@data-pipeline-specialist`	EP MCP integration (60+ tools), data quality, voting-records fallback to EP Open Data Portal.
🎨 `@frontend-specialist`	HTML5/CSS3, WCAG 2.1 AA accessibility, multi-language UI, RTL support.
✅ `@quality-engineer`	Vitest + Playwright, HTML validation, accessibility testing, performance benchmarking.
⚙️ `@devops-engineer`	gh-aw workflow compilation, GitHub Actions, S3/CloudFront deploy, MCP gateway.
📚 `@documentation-architect`	C4 models, Mermaid diagrams, ARCHITECTURE.md, ADRs.
🛡️ `@security-architect`	ISMS, GDPR, NIS2, EU CRA compliance — reviews data classification of intelligence products.
📋 `@product-task-agent`	Issue creation, ISMS tracking, capability-roadmap coordination.
📣 `@marketing-specialist`	Privacy-first multi-language engagement, GDPR-compliant outreach.
💼 `@business-development-specialist`	Strategic planning, civic-tech partnerships, sustainable transparency models.

🛠️ Infrastructure agents (maintain workflows and CI hygiene)

agentic-workflows.agent.md · news-generation.agent.md · ci-cleaner.agent.md · contribution-checker.agent.md · create-safe-output-type.agent.md · custom-engine-implementation.agent.md · grumpy-reviewer.agent.md · interactive-agent-designer.agent.md · technical-doc-writer.agent.md · w3c-specification-writer.agent.md

🐛 Debugging

# View TypeScript compilation
npm run build:check

# Test article generation (requires existing analysis artifacts)
npm run generate-article -- --run analysis/daily/YYYY-MM-DD/article-type

💻 IDE Setup

VS Code Extensions:

ESLint
Prettier
HTMLHint

VS Code Settings:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

❓ Questions?

Open an issue for bugs or feature requests
Check docs/CODE_STANDARDS.md for code guidelines
Review existing code for examples
Contact maintainers via GitHub

🏆 Security Badge Maintenance

Contributing to Badge Status

When contributing, be aware of how your changes may affect security badges:

OpenSSF Scorecard

Your PR may affect the scorecard if it:

Modifies GitHub Actions workflows
Adds/removes dependencies
Changes branch protection settings
Adds security scanning tools

Best Practices:

Pin all GitHub Actions to SHA hashes (not tags)
Use maintained, official actions when possible
Add security tests for new attack surfaces
Keep dependencies up-to-date

REUSE Compliance

All new files must include proper license headers or be covered by .reuse/dep5:

For JavaScript files:

// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
// SPDX-License-Identifier: Apache-2.0

For configuration files: Add entries to .reuse/dep5 following existing patterns

Test Coverage

New code must maintain ≥80% line coverage, ≥75% branch coverage:

Add unit tests for new functions
Add integration tests for new workflows
Add E2E tests for user-facing features

SonarCloud Quality Gate

When SonarCloud is enabled, PRs will be checked for:

Code coverage (target: 80%)
Code smells and technical debt
Security vulnerabilities
Maintainability rating (target: A)

See README.md - Badge Maintenance for detailed badge status and procedures.

🛡️ ISMS Compliance & Security-Policy Alignment

EU Parliament Monitor operates under the Hack23 ISMS framework. All contributions must align with these public policies — both in code (Secure Development Policy) and in conduct (Acceptable Use Policy).

🏛️ Policy	🎯 Why it applies	📌 What you must do
🛠️ Secure Development Policy	All code changes go through SSDLC gates	Threat-model new pipelines; pin actions to SHAs; no eval/dynamic code
📋 Information Security Policy	Integrity of analysis + confidentiality of methodology notes	Cite primary EP / IMF / World Bank sources; never leak credentials
🤖 AI Policy	Analysis is AI-assisted and must be auditable	Apply Pass-1 + Pass-2 review; disclose assumptions and uncertainty
🏷️ Classification Policy	Only public open-source material is used	No paywalled, leaked, or embargoed material in artifacts
🐛 Vulnerability Management	Severity-based remediation SLAs	Follow the SECURITY.md disclosure timeline
🔍 Threat Modelling Policy	New attack surfaces require STRIDE analysis	Update THREAT_MODEL.md for changes that touch CIA assets
🔐 Cryptography Policy	No deprecated algorithms (MD5, SHA-1, DES, 3DES)	Use modern crypto only; rely on platform / OIDC primitives
🚒 Incident Response Plan	Coordinated handling of security incidents	Notify security@hack23.com for any suspected incident
📜 Open Source Policy	Governance, licence headers, REUSE compliance	Apache-2.0 SPDX headers on every new code file
🇪🇺 CRA Conformity Assessment	EU Cyber Resilience Act compliance	See CRA-ASSESSMENT.md for the project conformity table

📚 Internal docs every contributor should know

Topic	Document
🏛️ Architecture	ARCHITECTURE.md · DATA_MODEL.md · FLOWCHART.md · STATEDIAGRAM.md · MINDMAP.md
📰 Article generation	Article-Generation.md — full Stage A→E pipeline
🧠 Analysis methodology	analysis/methodologies/ (17 methodologies) · analysis/templates/ (51 templates)
🛡️ Security	SECURITY.md · SECURITY_ARCHITECTURE.md · THREAT_MODEL.md · CRA-ASSESSMENT.md · CLASSIFICATION.md
⚙️ CI/CD	WORKFLOWS.md · .github/workflows/README.md · .github/prompts/README.md
🧪 Testing	UnitTestPlan.md · E2ETestPlan.md · test/README.md · e2e/README.md
💼 Business / lifecycle	SWOT.md · BCPPlan.md · End-of-Life-Strategy.md · FinancialSecurityPlan.md

🌐 Hack23 Ecosystem

EU Parliament Monitor is part of the broader Hack23 civic-tech and security portfolio. Cross-pollination is welcome — many architectural patterns and ISMS controls are shared.

🏛️ Project	🎯 Focus	🔗 Link
🌐 Hack23 Homepage	Organisation site, ISMS hub	hack23.com · `Hack23/homepage`
📜 ISMS-PUBLIC	Public ISO 27001 / NIST CSF / CIS / GDPR / NIS2 / EU CRA policies	`Hack23/ISMS-PUBLIC`
🔌 European Parliament MCP Server	TypeScript MCP server with 60+ EP open-data tools	`Hack23/European-Parliament-MCP-Server`
🇸🇪 Riksdag Monitor	Swedish Parliament monitor (sister project, foundation for this codebase)	`Hack23/riksdagsmonitor`
🕵️ CIA	Swedish Parliament intelligence platform (Java/Spring)	`Hack23/cia`
✅ CIA Compliance Manager	CIA-triad compliance dashboard (TypeScript)	`Hack23/cia-compliance-manager`
🥋 Black Trigram	Korean martial-arts game with security focus	`Hack23/blacktrigram`

📜 License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0 — the same licence that covers the rest of the project. All new code files must include SPDX headers:

// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
// SPDX-License-Identifier: Apache-2.0

Configuration files without headers must be covered by entries in .reuse/dep5.

🙏 Thank you for contributing to EU Parliament Monitor! 🇪🇺

Maintained by Hack23 AB — Intelligence Operations Team under the Hack23 ISMS framework.

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History