Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The GoGovSG contributing guidelines define the procedures for reporting issues, proposing features, and submitting code changes to the official Singapore government link shortener. These guidelines ensure that contributions maintain the security, reliability, and official status of the links served across the go.gov.sg, for.edu.sg, and for.sg environments.
Contributors must adhere to legal requirements, including the submission of a Contributor License Agreement (CLA), and follow specific technical workflows for local development and pull requests.
Legal Requirements
You must submit a Contributor License Agreement (CLA) before your contributions can be accepted. This agreement allows the Government Technology Agency (GovTech) to use and redistribute your contributions while you retain the copyright. If you have previously submitted a CLA for any GovTech project, you do not need to submit it again.
Sources: CONTRIBUTING.md:7-13
Communication and Issue Reporting
You must discuss any proposed changes via an issue or email with the repository owners before starting work. This process applies to both bug reports and feature requests.
Bug Reports
When you submit a bug report, include the following details:
- Clear and descriptive title.
- Exact steps to reproduce the behavior.
- Expected versus actual behavior.
- Specific examples, screenshots, or animated GIFs.
Feature Requests
When you submit a feature request, provide:
- The motivation for the change.
- Alternative solutions you considered.
- Context explaining why the feature is useful.
Sources: CONTRIBUTING.md:17-42
Development Environment Setup
GoGovSG requires Node.js version 18 (or 24 as specified in package.json), Docker, and docker-compose.
Local Initialization
- Clone the repository:
git clone git@github.com:opengovsg/GoGovSG.git. - Install dependencies:
pnpm install. - Start the development environment:
pnpm run dev.
The pnpm run dev command utilizes docker-compose to spin up a PostgreSQL database and a Redis container.
Sources: README.md:58-75, package.json:43
Architecture Overview
The application consists of a React frontend and a Node.js/Express backend. During development, two servers run concurrently.
The Webpack dev server proxies /api requests to the backend server.
Sources: README.md:77-85, webpack.config.ts:133-144
Technical Standards
Code Quality and Formatting
The project uses Rust-based tools for speed and consistency:
- Linter:
oxlintidentifies patterns in JavaScript and TypeScript. - Formatter:
oxfmt(Prettier-compatible) handles code style. - Type Checking:
tscvalidates TypeScript configurations.
| Command | Action |
|---|---|
pnpm run lint | Runs oxlint type-aware checks |
pnpm run format | Applies formatting fixes |
pnpm run typecheck | Validates server and client TS configs |
Sources: package.json:11-15, README.md:195-204
Build Process
The build process compiles TypeScript and bundles assets using Webpack.
tsccompiles server-side TypeScript to thebuilddirectory.webpackbundles client-side code into thedistdirectory.copyfilesmoves views and assets into the final build structure.
Sources: package.json:17-18, webpack.config.ts:60-70, tsconfig.json:33-35
Pull Request Process
When you are ready to submit a Pull Request (PR), follow these steps:
- Dependency Management: Remove any install or build dependencies before the end of the build layer.
- Documentation: Update
README.mdif your changes affect the interface, such as new environment variables, ports, or container parameters. - Review: You require the sign-off of two other developers to merge. If you lack merge permissions, request the second reviewer to merge for you.
Sources: CONTRIBUTING.md:46-56
Environment Variables
New features often require configuration. You must define these in src/server/config.ts. The application validates required variables at boot time and will exit if they are missing.
const requiredVars: string[] = [
'DB_URI',
'REPLICA_URI',
'OG_URL',
'REDIS_OTP_URI',
'REDIS_SESSION_URI',
'REDIS_REDIRECT_URI',
'REDIS_STAT_URI',
'REDIS_SAFE_BROWSING_URI',
'SESSION_SECRET',
'VALID_EMAIL_GLOB_EXPRESSION',
'AWS_S3_BUCKET',
'API_KEY_SALT',
]
Sources: src/server/config.ts:22-35
Testing
You must ensure your changes do not break existing functionality by running the test suite.
| Test Type | Command | Description |
|---|---|---|
| Unit | pnpm run test | Runs Jest unit tests |
| Integration | pnpm run test:integration | Runs integration tests |
| E2E | pnpm run test:e2e | Runs Playwright end-to-end tests |
Sources: package.json:23-28
Following these guidelines ensures that GoGovSG remains a trusted platform for Singapore government officers to share safe and recognizable short links with citizens.