Skip to main content

Contributing

We welcome contributions to Pulse! This guide will help you get started.

How to Contribute​

1. Fork the Repository​

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/your-username/pulse.git
    cd pulse

2. Create a Feature Branch​

git checkout -b feature/amazing-feature

3. Make Your Changes​

  • Write clean, maintainable code
  • Follow the existing code style
  • Add tests for your changes
  • Update documentation as needed

4. Write Tests​

Ensure your changes are tested:

Frontend Tests

cd pulse-ui
npm test

Backend Tests

cd backend/server
mvn test

Android SDK Tests

cd pulse-android-otel
./gradlew check

React Native SDK Tests

cd pulse-react-native-otel
npm test

5. Format Code​

Format your code before committing:

Frontend

cd pulse-ui
npm run format

Backend

  • Follow Checkstyle rules
  • Use Google Java Format

Android

cd pulse-android-otel
./gradlew spotlessApply

React Native

cd pulse-react-native-otel
yarn lint --fix

6. Commit Your Changes​

We follow the Conventional Commits specification:

  • fix: bug fixes, e.g. fix crash due to deprecated method
  • feat: new features, e.g. add new method to the module
  • refactor: code refactor, e.g. migrate from class components to hooks
  • docs: changes to documentation, e.g. add usage example
  • test: adding or updating tests, e.g. add integration tests
  • chore: tooling changes, e.g. change CI config

Example commit message:

git commit -m "feat: add user authentication endpoint"

7. Push and Create Pull Request​

git push origin feature/amazing-feature

Then create a pull request on GitHub.

Code Style​

Frontend (React/TypeScript)​

  • ESLint: Follow ESLint rules
  • Prettier: Use Prettier for formatting
  • TypeScript: Use TypeScript for type safety
  • Naming: Use camelCase for variables, PascalCase for components

Backend (Java/Vert.x)​

  • Google Java Style Guide: Follow Google Java Style Guide
  • Lombok: Use Lombok to reduce boilerplate
  • JavaDoc: Write comprehensive JavaDoc comments
  • Naming: Use meaningful variable and method names

Android (Kotlin)​

  • Spotless: Use Spotless with ktlint
  • Kotlin Style: Follow Kotlin coding conventions
  • Documentation: Add KDoc comments for public APIs

React Native (TypeScript)​

  • ESLint: Follow ESLint rules
  • Prettier: Use Prettier for formatting
  • TypeScript: Use TypeScript for type safety

Development Workflow​

Setting Up Development Environment​

  1. Install Prerequisites

    • Docker 20.10+
    • Java 17+
    • Node.js 18+
    • Maven 3.8+
    • Android Studio (for Android development)

  2. Clone and Setup

    git clone https://github.com/dream-horizon-org/pulse.git
    cd pulse

  3. Start Services

    cd deploy
    docker-compose up -d

Running Tests​

Run All Tests

# Frontend
cd pulse-ui && npm test

# Backend
cd backend/server && mvn test

# Android SDK
cd pulse-android-otel && ./gradlew check

# React Native SDK
cd pulse-react-native-otel && npm test

Building​

Frontend

cd pulse-ui
npm run build

Backend

cd backend/server
mvn clean package

Android SDK

cd pulse-android-otel
./gradlew assemble

React Native SDK

cd pulse-react-native-otel
npm run build

Pull Request Guidelines​

When creating a pull request:

  • Clear Description: Provide a clear description of changes
  • Link Issues: Link related issues if applicable
  • Include Tests: Ensure tests are included and passing
  • Update Documentation: Update relevant documentation
  • CI Passing: Ensure CI checks pass
  • Small PRs: Prefer small, focused pull requests

Pull Request Template​

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added and passing

Reporting Issues​

When reporting issues:

  1. Check Existing Issues: Search for similar issues first
  2. Provide Details: Include:
    • Description of the issue
    • Steps to reproduce
    • Expected behavior
    • Actual behavior
    • Environment details (OS, versions, etc.)
    • Relevant logs or screenshots

Feature Requests​

For feature requests:

  1. Check Existing Requests: Search for similar requests
  2. Describe Use Case: Explain why the feature would be useful
  3. Provide Examples: Include examples of how it would be used

Documentation Contributions​

Documentation improvements are always welcome:

  • Fix typos or grammar errors
  • Improve clarity and readability
  • Add examples or use cases
  • Update outdated information
  • Add missing documentation

Questions?​

  • GitHub Discussions: Use GitHub Discussions for questions
  • Issues: Open an issue for bugs or feature requests
  • Pull Requests: Submit a PR for code contributions

Recognition​

Contributors will be recognized in:

  • Project README
  • Release notes
  • GitHub contributors page

Thank you for contributing to Pulse! 🎉

Next Steps​