Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
443 lines (301 loc) · 8.65 KB

CONTRIBUTING.md

File metadata and controls

443 lines (301 loc) · 8.65 KB
Raw

🤝 Contributing to Pollution Control Hub

Thank you for your interest in contributing to Pollution Control Hub! We appreciate every contribution, whether it's fixing bugs, improving the UI, enhancing documentation, or implementing new features.

Our goal is to maintain a welcoming, collaborative, and high-quality open-source project. Please read this guide before contributing.

📑 Table of Contents

  • Code of Conduct
  • Ways to Contribute
  • Getting Started
  • Development Setup
  • Finding an Issue
  • Issue Labels
  • Branch Naming Convention
  • Development Guidelines
  • Testing Guidelines
  • Code Formatting & Linting
  • Commit Message Convention
  • Pull Request Process
  • Review Workflow
  • Pull Request Checklist
  • Reporting Bugs
  • Suggesting Features
  • Community & Support

🌍 Code of Conduct

Please follow our Code of Conduct when contributing to this project.

We expect all contributors to:

  • Be respectful and inclusive.
  • Provide constructive feedback.
  • Maintain a positive and collaborative environment.

🚀 Ways to Contribute

You can contribute by:

  • 🐞 Fixing bugs
  • ✨ Adding new features
  • 🎨 Improving UI/UX
  • 📱 Enhancing responsiveness
  • 📚 Improving documentation
  • ⚡ Refactoring code
  • ♿ Improving accessibility
  • 🧪 Writing or improving unit and E2E tests
  • 🔒 Improving performance or security

🛠 Getting Started

1. Fork the Repository

Click the Fork button in the upper-right corner of the repository.

2. Clone Your Fork

git clone [https://github.com/Aditya8369/Pollution-Control-Hub.git](https://github.com/Aditya8369/Pollution-Control-Hub.git)
cd pollution-control-hub

3. Install Dependencies

npm install

4. Start the Development Server

npm run dev

The project will be available at:

http://localhost:5173

📌 Finding an Issue

Browse the Issues section and look for:

  • good first issue
  • beginner friendly
  • help wanted
  • bug
  • enhancement

If you would like to work on an issue:

  1. Comment on the issue.
  2. Wait until you're assigned (if required).
  3. Create a branch.
  4. Start working.

Please avoid working on issues already assigned to someone else unless requested by a maintainer.

🏷 Issue Labels

The repository uses labels to organize work.

Label Meaning
good first issue Suitable for first-time contributors
beginner friendly Easy tasks for newcomers
bug Something isn't working correctly
enhancement Improvement to an existing feature
feature request New functionality
documentation Documentation updates
UI/UX User interface improvements
performance Optimization tasks
accessibility Accessibility improvements
help wanted Community contributions needed
high priority Important issue requiring attention
duplicate Already reported elsewhere
invalid Not considered a valid issue
wontfix Will not be addressed

🌿 Branch Naming Convention

Create a separate branch for every contribution.

Use the following naming format:

feature/feature-name
bugfix/issue-name
fix/issue-name
docs/update-readme
refactor/component-name
style/navbar-spacing
test/add-unit-tests

Examples:

feature/community-reports

bugfix/mobile-sidebar

docs/contributing-guide

style/dashboard-spacing

refactor/aqi-service

Never commit directly to the main branch.

💻 Development Guidelines

Please follow these guidelines:

  • Keep components reusable.
  • Follow the existing folder structure.
  • Write meaningful variable names.
  • Avoid duplicate code.
  • Remove unused imports.
  • Use consistent formatting.
  • Keep pull requests focused on a single issue.
  • Ensure responsiveness.
  • Preserve accessibility.

🧪 Testing Guidelines

Ensuring code stability is critical. Before submitting a pull request, you must run and pass all test suites locally.

Running Unit Tests (Vitest)

This project uses Vitest and React Testing Library for automated component and utility tests.

To run all unit tests:

npm run test

To run tests in interactive watch mode:

npm run test:watch

Running End-to-End (E2E) Tests (Playwright)

To ensure critical user flows work correctly across browsers, execute the Playwright E2E test suite:

npx playwright test

If you need to view the test runs interactively using the Playwright UI runner:

npx playwright test --ui

🧹 Code Formatting & Linting

To maintain a clean and unified codebase style, ensure your code adheres to standard formatting and linting practices before pushing.

  • Run your linter/formatter (if configured via package scripts) or ensure your IDE uses standard Prettier/ESLint rules.
  • Avoid introducing unused variables or syntax errors that cause build failures.

📂 Suggested Project Structure

src/
│
├── assets/
├── components/
├── hooks/
├── pages/
├── services/
├── utils/
├── styles/
├── App.jsx
└── main.jsx

📝 Commit Message Convention

Use descriptive commit messages following the Conventional Commits style.

Examples:

feat: add pollution trend chart

fix: resolve mobile navigation overflow

docs: improve installation instructions

style: update dashboard spacing

refactor: simplify AQI calculation logic

test: add unit tests for AQI utilities

Avoid messages like:

update

changes

fixed stuff

done

new

🔄 Pull Request Process

  1. Sync your fork with the latest changes.
git checkout main
git pull upstream main
  1. Create a new branch.
git checkout -b feature/your-feature

  1. Make your changes.

  2. Run unit and E2E tests locally to verify everything passes.

npm run test
npx playwright test
  1. Commit your work.
git commit -m "feat: add pollution heatmap"
  1. Push your branch.
git push origin feature/your-feature
  1. Open a Pull Request referencing the issue number (e.g., Closes #437).

📋 Pull Request Template

Description

Briefly explain your changes.

Related Issue

Closes #IssueNumber

Type of Change

  • Bug Fix
  • New Feature
  • UI Improvement
  • Documentation
  • Refactoring
  • Performance
  • Accessibility

Screenshots

Include screenshots or screen recordings if the UI has changed.

Additional Notes

Provide any additional context if necessary.

👀 Review Workflow

Once your Pull Request is submitted:

  1. Automated checks and test suites (Vitest & Playwright E2E) will run.
  2. A maintainer will review your changes.
  3. You may be asked to make revisions.
  4. Push additional commits to the same branch.
  5. The Pull Request will be reviewed again.
  6. Once approved, it will be merged.

Please be patient during the review process.

✅ Pull Request Checklist

Before submitting your Pull Request, ensure that:

  • My code builds successfully.
  • I passed all local Vitest unit tests (npm run test).
  • I passed all Playwright E2E tests (npx playwright test).
  • I tested my changes manually.
  • No console errors remain.
  • I followed the existing coding style and formatting rules.
  • I updated documentation if required.
  • My branch is up to date.
  • My Pull Request focuses on a single issue.
  • I have added screenshots for UI changes.
  • I have linked the related issue.

🐞 Reporting Bugs

Please include:

  • Clear title
  • Description
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Browser
  • Operating system
  • Screenshots (if applicable)
  • Console logs (if relevant)

💡 Suggesting Features

Feature requests should include:

  • Problem statement
  • Proposed solution
  • Expected outcome
  • Mockups (optional)
  • Additional context

📚 Documentation Contributions

Documentation improvements are always welcome.

Examples include:

  • Fixing grammar
  • Updating setup instructions
  • Adding examples
  • Improving explanations
  • Adding screenshots
  • Improving code comments

❤️ Thank You

Every contribution—big or small—helps improve Pollution Control Hub and supports our mission of making environmental information more accessible and actionable.

We appreciate your time, effort, and collaboration.

Happy Contributing! 🚀