Thank you for your interest in contributing to EU Parliament Monitor! This document provides guidelines and instructions for contributing to the project.
By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
git clone https://github.com/YOUR_USERNAME/euparliamentmonitor.git
cd euparliamentmonitor
npm install
git checkout -b feature/your-feature-name
# Generate news articles (with MCP disabled for testing)
USE_EP_MCP=false npm run generate-news -- --types=week-ahead --languages=en
# Generate index pages
npm run generate-news-indexes
# Generate sitemap
npm run generate-sitemap
# Serve locally
npm run serve
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
All contributions must meet these quality standards:
All contributions must include appropriate tests:
# Run unit & integration tests
npm test
# Check coverage
npm run test:coverage
# Run specific test file
npx vitest test/unit/your-test.test.js
# 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:
Required for all code changes:
.prettierrc.json configurationAll exported functions must include:
/**
* Brief function description
* @param {type} paramName - Parameter description
* @returns {type} Return value description
*/
Security Architecture: All security changes must align with the Security Architecture and ISMS Secure Development Policy.
Security Requirements:
=== instead of ==eval() and new Function()Security Review Checklist:
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
The project uses Husky and lint-staged to automatically:
These hooks run automatically on git commit. To bypass (not recommended):
git commit --no-verify
Use conventional commits format:
<type>(<scope>): <description>
[optional body]
[optional footer]
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code style changes (formatting, etc.)refactor: Code refactoringtest: Adding or updating tests (use this for test-related commits!)chore: Maintenance tasksci: CI/CD changesgit 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"
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:
# Generate news with your changes
USE_EP_MCP=false npm run generate-news -- --types=week-ahead --languages=en
# 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:
Include in your PR description:
Your PR must pass these automated checks:
euparliamentmonitor/
├── .github/ # GitHub workflows and configuration
│ ├── workflows/ # CI/CD workflows
│ └── agents/ # Custom GitHub Copilot agents
├── scripts/ # Core application scripts
│ ├── generate-news-enhanced.js # News generation
│ ├── generate-news-indexes.js # Index generation
│ ├── generate-sitemap.js # Sitemap generation
│ ├── article-template.js # HTML templates
│ └── ep-mcp-client.js # MCP client
├── 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
EU Parliament Monitor includes 8 specialized GitHub Copilot agents:
@product-task-agent - Issue creation and coordination@news-journalist - Content generation@frontend-specialist - UI/UX improvements@data-pipeline-specialist - MCP integration@devops-engineer - CI/CD automation@security-architect - Security compliance@documentation-architect - Documentation@quality-engineer - Testing and validationSee .github/agents/README.md for usage.
# Enable verbose logging
DEBUG=* npm run generate-news
# Generate with placeholder content (no MCP)
USE_EP_MCP=false npm run generate-news
VS Code Extensions:
VS Code Settings:
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
}
}
When contributing, be aware of how your changes may affect security badges:
Your PR may affect the scorecard if it:
Best Practices:
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
New code must maintain ≥80% line coverage, ≥75% branch coverage:
When SonarCloud is enabled, PRs will be checked for:
See README.md - Badge Maintenance for detailed badge status and procedures.
By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.
Thank you for contributing to EU Parliament Monitor! 🇪🇺