Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
166 lines (117 loc) · 5.95 KB

CONTRIBUTING.md

File metadata and controls

166 lines (117 loc) · 5.95 KB

Contributing to Upstream Pulse

Thank you for your interest in contributing to Upstream Pulse! This document provides guidelines and information for contributors.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Dashboard Users — Start Here

You don't need to write code to contribute. But because this is an open-source project that can be deployed by anyone, it's important to use the right channel depending on what you need.

Public GitHub Issues (for the open-source project)

Use these for requests and bugs that improve the software for everyone:

I want to... Template
Add a new upstream project or org to the codebase Request New Project
Report a bug in data collection, sync, or parsing logic Data Collection Bug
Suggest a feature or report a dashboard UI issue Feedback

Want to check what's already tracked? See docs/upstream-projects.md for the full list.

Deployment-Specific Issues (contact your admin)

If your issue is about your team's specific dashboard instance — wrong seat counts, a person missing from the team list, identity merge requests, or stale data — these should not be filed as public GitHub issues because they contain internal team information.

Instead, contact your dashboard administrator — you can find their info on the About page of your dashboard. Admins can fix team member records, trigger re-syncs, and adjust identity mappings directly.

Developer Contributions

The rest of this guide is for developers who want to contribute code changes.

Reporting Issues

  • Use GitHub Issues to report bugs or request features
  • Check existing issues before creating a new one
  • Include steps to reproduce for bug reports
  • Provide as much context as possible

Submitting Changes

  1. Fork the repository
  2. Create a feature branch from main: 
    git checkout -b feature/your-feature-name
  3. Make your changes following the coding standards below
  4. Test your changes locally
  5. Commit with clear, descriptive messages
  6. Push to your fork and open a Pull Request

Pull Request Guidelines

  • Keep PRs focused and reasonably sized
  • Describe what the PR does and why
  • Reference any related issues
  • Ensure the build passes before requesting review

Development Setup

Prerequisites

  • Node.js 20+
  • Docker & Docker Compose

Getting Started

# Clone your fork
git clone https://github.com/your-username/upstream-pulse.git
cd upstream-pulse

# Set up environment
cp .env.example .env
# Edit .env with your credentials

# Start services
docker-compose up -d postgres redis

# Install and run backend
cd backend
npm install
npm run db:migrate
npm run dev

# Install and run frontend (separate terminal)
cd frontend
npm install
npm run dev

Useful Commands

Command Description
npm run dev Start backend + frontend concurrently
npm run dev:backend Start backend only
npm run dev:frontend Start frontend only
npm run build Build both backend and frontend
npm run db:migrate Run database migrations
npm run db:studio Open Drizzle Studio (DB GUI)

Adding a New Upstream Organization

Upstream Pulse uses a centralized org registry (backend/src/shared/config/org-registry.ts) that declares every supported upstream organization. To add a new org:

  1. Add an entry to the ORG_REGISTRY array with the org's GitHub slug, governance model, and (optionally) community repo details.
  2. If the org has structured leadership data (steering committee, maintainers list, WG YAML), configure the communityRepo and leadershipFiles fields so the leadership collector knows what to parse.
  3. Submit a PR — the system will automatically pick up the new org on the next scheduled run.

For a detailed walkthrough with field-by-field explanations and testing instructions, see docs/adding-an-org.md.

Coding Standards

TypeScript

  • Use TypeScript for all new code
  • Enable strict mode
  • Prefer const over let; avoid var
  • Use explicit return types for public functions

Backend

  • Use Fastify for HTTP routes
  • Use Drizzle ORM for database queries
  • Use Winston for logging
  • Follow the existing module structure under backend/src/modules/

Frontend

  • Use React functional components with hooks
  • Use TanStack Query for data fetching
  • Use Tailwind CSS for styling
  • Follow the component structure under frontend/src/components/

Git Commit Messages

  • Use present tense ("Add feature" not "Added feature")
  • Keep the first line under 72 characters
  • Reference issues when applicable (e.g., "Fix #123")

Project Structure

upstream-pulse/
├── backend/              # Fastify API server + BullMQ workers
│   └── src/
│       ├── jobs/         # BullMQ job definitions and workers
│       ├── modules/      # Feature modules (api, collection, identity, etc.)
│       ├── scripts/      # Database seeds and utility scripts
│       └── shared/       # Config (incl. org registry), database, types, utilities
├── frontend/             # React + Vite dashboard
│   └── src/
│       ├── components/   # Reusable UI components
│       └── pages/        # Route-level page components
├── deploy/               # OpenShift deployment manifests and scripts
└── docs/                 # Additional documentation

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.