Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
293 lines (218 loc) · 9.82 KB

CONTRIBUTING.md

File metadata and controls

293 lines (218 loc) · 9.82 KB
Raw

Contributing to OpenNG REST API 🇳🇬

First off, thank you for considering contributing to OpenNG REST API! 🎉

OpenNG is an open-source initiative providing a standardized, structured, and developer-friendly RESTful API for Nigerian geographic, demographic, political, educational, cultural, and historical data.

This guide contains everything you need to set up your local development environment, explore the codebase, run tests, and submit your contributions.

📖 Table of Contents

Code of Conduct

All contributors, maintainers, and community members are expected to adhere to our Code of Conduct. Please report any unacceptable behavior according to the enforcement guidelines.

How Can I Contribute?

Reporting Bugs

Before submitting a new bug report, search existing issues to see if the problem has already been logged.

When opening a bug report, please include:

  • A clear and descriptive title.
  • Step-by-step reproduction instructions.
  • The HTTP method, request URL, headers, and response payload.
  • Your Node.js version, PostgreSQL version, and OS environment.
  • Expected behavior vs. actual behavior.

Suggesting Features & Data Additions

We actively encourage proposals for new datasets (e.g., historical milestones, tourist destinations, LGA council wards, educational programs), schema expansions, and performance improvements.

Please provide:

  • A concise summary and use case for the proposed feature.
  • Proposed REST API endpoints, DTO models, and query filters.
  • Reputable data sources or references for verification.

Submitting Pull Requests

  1. Search open and closed PRs to ensure the task is not already in progress.
  2. Fork the repository and create your feature branch from main.
  3. Follow the development and commit guidelines outlined below.

Local Development Setup

Prerequisites

  • Node.js: v20.x or v22.x (LTS recommended)
  • npm: v10+ (or pnpm / yarn)
  • PostgreSQL: v15+ running locally or via Docker

Cloning & Installing Dependencies

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/<your-username>/OpenNG.git
cd OpenNG

# Install dependencies
npm install

Environment Variables Configuration

Create a .env file in the root directory by duplicating .env.local or env.examples:

cp .env.local .env

Configure your environment settings:

# Server Port
PORT=3000

# Environment Mode (development / production / test)
NODE_ENV=development

# PostgreSQL Connection String
DATABASE_URL="postgresql://postgres:password@localhost:5432/openng?schema=public"

Database Setup & Prisma ORM

OpenNG uses Prisma ORM with PostgreSQL:

# Generate the Prisma Client
npx prisma generate

# Inspect database schema and launch Prisma Studio GUI
npx prisma studio

# Pull database changes into schema.prisma if schema was updated externally
npx prisma db pull

Running the Application Locally

# Start in development watch mode (auto-reload on save)
npm run start:dev

# Start in debug mode
npm run start:debug

# Build and start the compiled production server
npm run build
npm run start:prod

Once started, the Interactive Swagger / OpenAPI Documentation is available at:
👉 http://localhost:3000/api/v1/docs

Available NPM Scripts

Command Description
npm run start:dev Starts the NestJS application in watch mode with hot reloading
npm run start:debug Starts the application with the Node.js V8 debugger attached
npm run build Compiles TypeScript files into the dist/ directory
npm run start:prod Runs the compiled production build from dist/main
npm run format Auto-formats all TypeScript code using Prettier
npm run lint Analyzes code and fixes ESLint violations automatically
npm run test Executes Jest unit test suite
npm run test:watch Runs Jest in interactive watch mode
npm run test:cov Runs tests and generates a test coverage report in coverage/
npm run test:e2e Runs end-to-end integration tests (test/jest-e2e.json)

Project Architecture & Directory Structure

openng-rest/
├── prisma/
│   ├── schema.prisma        # Prisma data models and PostgreSQL relations
│   └── prisma.config.ts     # Prisma CLI configuration
├── src/
│   ├── common/              # Shared guards, interceptors, middleware, constants
│   │   ├── constants/       # Global constants & environment helpers
│   │   ├── filters/         # HTTP exception filters
│   │   ├── interceptors/    # Logging, response transformation & metrics
│   │   └── middleware/       # Security and request headers middleware
│   ├── docs/                # OpenAPI / Swagger configuration module
│   ├── health/              # Healthcheck and diagnostic endpoints
│   ├── home/                # Root metadata & welcome handlers
│   ├── modules/             # Core domain REST modules
│   │   ├── culture/         # Ethnic groups, languages, festivals controllers & services
│   │   ├── education/       # Universities, polytechnics, colleges
│   │   ├── geography/       # States, LGAs, wards, regions, constituencies
│   │   ├── history/         # Historical events, historical figures
│   │   ├── politics/        # Governors, presidents, public offices, parties
│   │   ├── system/          # System telemetry & metadata
│   │   └── tourism/         # Tourism sites, landmarks, cultural locations
│   ├── prisma/              # PrismaService integration
│   ├── app.module.ts        # Root NestJS application module
│   └── main.ts              # Server bootstrap, Swagger setup, Helmet, Pino logger
├── test/                    # End-to-end (E2E) and integration tests
├── CODE_OF_CONDUCT.md       # Contributor Covenant Code of Conduct
├── CONTRIBUTING.md          # Development and contribution guide
├── LICENSE                  # MIT License
└── package.json             # Project dependencies and script definitions

Development Workflow

Branching Strategy

Always create dedicated feature branches with descriptive prefixes:

  • feat/<feature-name>: New REST endpoints, controllers, or module additions.
  • fix/<bug-name>: Bug fixes in controllers, services, or mappers.
  • docs/<doc-name>: Documentation, guides, and OpenAPI updates.
  • refactor/<refactor-name>: Structural refactoring without breaking API contracts.
  • test/<test-name>: Adding or modifying unit and E2E tests.

Conventional Commits

We follow the Conventional Commits specification:

<type>(<scope>): <short summary>

[optional detailed body]

[optional issue reference, e.g. Fixes #42]

Allowed Types:

  • feat: A new feature or REST endpoint
  • fix: A bug fix
  • docs: Documentation changes
  • style: Formatting, missing semicolons, whitespace
  • refactor: Code changes that neither fix a bug nor add a feature
  • perf: Code changes that improve performance
  • test: Adding or correcting tests
  • chore: Build tools, dependencies, config updates

Examples:

  • feat(geography): add senatorial districts endpoint under /states/:slug
  • fix(politics): correct office holder assumption date parsing
  • docs(readme): add OpenAPI curl examples

Code Quality, Formatting & Linting

Before pushing your changes, ensure code adheres to the formatting and linting rules:

# Format code
npm run format

# Run linter
npm run lint

Running Tests

Ensure all unit and integration tests pass:

# Run unit tests
npm run test

# Run E2E tests
npm run test:e2e

Submitting a Pull Request

  1. Verify your branch is up to date with main: 
    git checkout main
git pull origin main
git checkout feat/your-feature-name
git rebase main
  2. Run lint and tests: 
    npm run lint && npm run test
  3. Push to your fork: 
    git push origin feat/your-feature-name
  4. Open a Pull Request against Kim5Y/OpenNG main branch.
  5. Provide a clear PR description detailing:
    • What changed and why.
    • Any database or API schema impacts.
    • Steps taken to test and verify the change.

Community & Getting Help

Thank you for helping build a world-class open data platform for Nigeria! 🇳🇬