Contributing

Table of Contents

Welcome
Better Gov Overview
Ground Rules
Community Engagement
Share Ideas
Report issues and bugs
Before you start
Environment setup
Contribution Workflow
Resources

Welcome

Welcome to the Better Gov Contributing Guide and thank you for your interest in supporting the project!

We welcome contributions of all kinds. Whether you are a developer, designer, writer, or just someone with a great idea, there’s a place for you here.

Here are the types of contributions we currently accept and where to learn more in this guide:

Source Code – Fix bugs, add features, or improve existing code
Ideas – Share suggestions for improvements or new features
Bug Reporting – Help us identify and document issues
Translations – Make the project accessible in different languages
Documentation – Improve guides, tutorials, or reference docs
Data Scraping – Contribute data collection scripts or improvements

Better Gov is a community-led initiative to create a better and more usable Philippine national government website. It is an open-source project dedicated to improving access to government-related information and services through technology, transparency, and collaboration. To learn more about our purpose and goals, please read the README.

Ground rules

Before contributing, read our CODE OF CONDUCT to learn more about our community guidelines and expectations.

Community engagement

Refer to the following channels to connect with fellow contributors or to stay up-to-date with news about the Better Gov:

Join our project contributors on Discord.

To share your new ideas for the project, perform the following actions:

Reach out via email volunteers@bettergov.ph
Discord Ideas Forum: ⁠ideas
Submit ideas in Github Discussions

Report issues and bugs

If you encounter a problem with the project, please open an issue in this repository.

When reporting an issue, please include the following details to help us investigate:

Description – A clear and concise explanation of the problem.
Steps to reproduce – How to reproduce the issue (step by step).
Expected behavior – What you thought should happen.
Actual behavior – What actually happened instead.
Environment details – Your operating system, browser (if applicable), Node.js version, etc.
Screenshots or logs – If relevant, add screenshots or error logs.

Tip: Check existing issues before creating a new one to avoid duplicates.

Before you start

Before you start contributing, ensure you have the following:

Node.js (v22 or above recommended)
npm (v10 or above) or yarn (optional)
Git
A code editor like VS Code

Environment setup

To set up your environment, perform the following actions:

At the root of the project, create a .env file. See env.example for reference

Use the Node.js version specified in .nvmrc (recommended)

# If you have nvm installed:

nvm use

# Or if you have fnm installed:

fnm use

Install the dependencies
```
npm install
```
Start the development server
```
npm run dev
```

Setting up Search (Meilisearch)

BetterGov uses Meilisearch to power its search functionality. To set up search for local development:

Install and configure Meilisearch - Follow the detailed setup guide in docs/Meilisearch.md
Index your data - Load government services and directory data into the search engine
Test search functionality - Verify everything works by searching on your local site

The scripts documentation includes:

Platform-specific installation instructions (Windows, macOS, Linux)
Step-by-step configuration guide
Troubleshooting common issues
Documentation for all data processing scripts

For the complete guide, see docs/Meilisearch.md.

Contribution workflow

Official Github Docs on Forking a repository

Initial Setup

Fork the Repository on GitHub

Go to the main project repository (github.com/bettergovph/bettergov).
Click the "Fork" button to create a copy under your Github account.

Clone the Forked Repository to Local Machine

git clone https://github.com/<your-username>/bettergov.git
cd bettergov

Add the Original Repository as an Upstream

git remote add upstream https://github.com/bettergovph/bettergov.git

Branch creation

Update local main before creating a new branch

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Create a New Feature Branch

Create a branch using a prefix-based convention (feature/, fix/, docs/, etc.) to maintain clarity.

Format

<prefix>/<short-description>

Example

feature/add-login-form
fix/navbar-responsive-issue
docs/add-contributing-and-code-of-conduct

Tip: Keep branch names short, descriptive, and kebab-case.

Development Loop

Make Changes
Make sure your code passes linting and tests before committing.

git add .
git commit -a

⚠️ Important: Commit your changes following the Conventional Commits standard.

Commit messages

We follow Conventional Commits for all commit messages. This helps keep our history clean and readable.

Format

<type>[optional scope]: <short description>

Common Types Used

feat: → A new feature
fix: → A bug fix
docs: → Documentation only changes
style: → Code style or formatting changes (no logic)
refactor: → Code refactoring (no feature or fix)
test: → Adding or updating tests
chore: → Maintenance tasks (build process, dependencies, etc.)

Example

feat(button): add primary button variant
fix(navbar): correct mobile menu toggle
docs: add CONTRIBUTING.md and CODE_OF_CONDUCT.md

Push to the Forked Repository

git push -u origin feat/add-new-component

Sync with Upstream Again

If the upstream main branch has been updated while working, integrate changes into your feature branch to avoid conflicts.

git fetch upstream
git rebase upstream/main
git push

Pull requests

We use Pull Requests (PRs) to review and merge changes. Follow these steps when creating a PR:

Open a Pull Request to the main repository:

Target the main branch (or the branch specified by maintainers).
Provide a clear title and detailed description of your changes.
Reference any related issues (e.g., Closes #12).
AI-Assisted Work Disclosure: If you used AI tools to help generate or significantly modify code in your PR, please disclose this in the PR description. This helps maintainers conduct a more thorough review.

Wait for review:

Maintain open communication with reviewers.
Make any requested changes by committing in local feature branch
After making changes, commit and push to the same branch—the PR will update automatically..

git add .
git commit -m "refactor: address review feedback"
git push

A maintainer will merge your PR once it’s approved.