Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
373 lines (273 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

373 lines (273 loc) · 10.4 KB
Raw

Contributing to React Native Pay

Thank you for your interest in contributing to React Native Pay! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/react-native-pay.git
cd react-native-pay
  3. Add the upstream remote: 
    git remote add upstream https://github.com/gmi-software/react-native-pay.git

Development Setup

Prerequisites

  • Node.js (v18 or higher)
  • bun
  • React Native development environment
  • For iOS: Xcode and CocoaPods
  • For Android: Android Studio and Android SDK
  • Expo CLI (for running the example app)

Installation

# Install root dependencies
bun install

# Install package dependencies
cd package && bun install

# Install example app dependencies
cd ../example && bun install

# Generate Nitro bindings (required after cloning)
cd ../package
bun run specs

Running the Example App

The example app in /example is used for testing and verification:

cd example

# iOS
npx expo prebuild
npx expo run:ios

# Android
npx expo prebuild
npx expo run:android

Note: Payment functionality requires real devices. Simulator/Emulator support is limited.

Project Structure

react-native-pay/
├── package/              # Main library package
│   ├── src/              # TypeScript source
│   │   ├── hooks/        # React hooks
│   │   ├── specs/        # Nitro Module specifications (*.nitro.ts)
│   │   ├── types/        # TypeScript type definitions
│   │   ├── utils/        # Utility functions
│   │   └── plugin/       # Expo config plugins
│   ├── ios/              # iOS native code (Swift)
│   ├── android/          # Android native code (Kotlin, C++)
│   ├── nitrogen/         # Generated Nitro bindings (do not edit)
│   └── package.json
├── example/              # Example Expo app for testing
└── README.md

Development Workflow

1. Create a Branch

git checkout main
git pull upstream main
git checkout -b feature/your-feature-name

Use descriptive branch names:

  • feature/add-shipping-address
  • fix/google-pay-error-handling
  • docs/update-api-documentation

2. Make Your Changes

  • Write clean, maintainable code
  • Follow existing patterns and conventions
  • Add JSDoc comments for public APIs
  • Update types when adding new features

3. Test Your Changes

Before submitting a PR, ensure:

  • TypeScript compiles without errors: cd package && bun run typecheck
  • Linting passes: cd package && bun run lint
  • Automated tests pass: cd package && bun run test:ci
  • Example app runs on iOS (if applicable)
  • Example app runs on Android (if applicable)
  • Tested in both TEST and PRODUCTION modes (for payment features)

4. Update Documentation

  • Update README.md for API changes
  • Add code examples for new features
  • Update type definitions if needed
  • Docs site (docs/): The technical documentation is in the docs/ folder (Docusaurus, English). When you change public API, setup, or behavior, update the relevant page under docs/docs/ (e.g. api/use-payment-checkout.md, setup/ios-apple-pay.md). Run bun run docs:build locally to verify the site builds. The docs workflow runs only when a new tag is pushed (see .github/workflows/docs.yml), not on every PR.

AI Spec-Driven Development

This repository follows AI spec-driven development for important changes in package/.

The source of truth for architecture and behavior lives in .ai/specs/. Code and specs must evolve together.

Core Rules

  • Always check for an existing relevant spec before implementing changes.
  • For significant feature/API/architecture updates, update the matching spec in .ai/specs/.
  • For new modules or major new features, create a new spec file.
  • Keep each spec changelog updated with a dated entry.
  • If you add a new spec file, update .ai/specs/README.md specification table.

Naming and Structure

  • New spec files must follow: SPEC-{next-number}-{YYYY-MM-DD}-{kebab-title}.md
  • Follow the section guidance from .ai/specs/README.md and .ai/specs/AGENTS.md.
  • Include only applicable sections (for example: Overview, Architecture, API Contracts, Configuration, Changelog).

Practical Workflow

  1. Before coding
    • Read the related spec in .ai/specs/
    • Confirm constraints, contracts, and assumptions
  2. While implementing
    • Keep notes on behavior/API/config changes that must be reflected in specs
  3. After implementation
    • Update existing spec(s) or create a new one
    • Add a changelog entry with date and summary
    • Update .ai/specs/README.md if a new spec was created

Pull Requests

Include spec changes in the same PR as the code change whenever possible. If specs are intentionally deferred, explain why in the PR description.

Code Style

TypeScript

  • Follow existing TypeScript patterns in the codebase
  • Use TypeScript strict mode
  • Prefer explicit types over any
  • Export types from src/types/index.ts

Formatting

  • Prettier is configured and runs automatically
  • Use single quotes for strings
  • Use 2 spaces for indentation
  • No semicolons (as per project config)

Naming Conventions

  • Files: camelCase for utilities, PascalCase for components/types
  • Functions: camelCase
  • Types/Interfaces: PascalCase
  • Constants: UPPER_SNAKE_CASE

JSDoc Comments

Add JSDoc comments for all public APIs:

/**
 * Initiates a payment checkout flow.
 * @param request - Payment request configuration
 * @returns Promise resolving to payment result
 * @throws {PaymentError} If payment fails or is cancelled
 */
export async function checkout(request: PaymentRequest): Promise<PaymentResult> {
  // ...
}

Testing

Automated Tests

The library now includes automated tests using:

  • Jest for unit tests
  • React Native Testing Library for integration tests (hooks/components)

Run tests from the package/ workspace:

# Run all tests
cd package && bun run test

# Run tests in CI mode (single run, no watch)
cd package && bun run test:ci

# Run a single test file
cd package && bun run test -- src/hooks/__tests__/usePaymentCheckout.integration.test.ts

Manual Testing

Automated coverage does not replace device verification for payment flows. Manual testing is still required:

  1. Test on Real Devices: Payment features require real iOS/Android devices
  2. Test Both Platforms: Verify changes work on both iOS and Android
  3. Test Both Environments: Use both TEST and PRODUCTION payment environments
  4. Test Error Cases: Verify error handling works correctly

Testing Checklist

  • Unit and integration tests pass locally (cd package && bun run test:ci)
  • Payment flow completes successfully
  • Error handling works for invalid inputs
  • UI components render correctly
  • TypeScript types are correct
  • No console errors or warnings

Nitro Modules

This project uses Nitro Modules for native bindings.

Important Notes

  • Spec Files: Located in package/src/specs/*.nitro.ts
  • Generated Code: The package/nitrogen/ directory contains generated bindings - do not edit manually
  • Regeneration: After changing any *.nitro.ts file, run: 
    cd package
bun run specs
  • Type Generation: The specs command generates both native bindings and TypeScript types

Working with Nitro Specs

  1. Edit the .nitro.ts specification file
  2. Run bun run specs to regenerate bindings
  3. Implement native code in Swift (iOS) or Kotlin (Android)
  4. Test thoroughly on both platforms

Pull Request Process

Before Submitting

  1. Sync with upstream:

    git checkout main
git pull upstream main
git checkout your-branch
git rebase main

  2. Ensure all checks pass:

    • TypeScript compilation
    • Linting
    • Automated tests
    • Manual testing

  3. Write a clear description:

    • What changes were made
    • Why the changes were needed
    • How to test the changes
    • Any breaking changes

PR Description Template

## Summary
- Brief description of changes
- Key improvements or fixes

## Changes
- List of specific changes made

## Testing
- [ ] TypeScript compiles: `cd package && bun run typecheck`
- [ ] Linting passes: `cd package && bun run lint`
- [ ] Automated tests pass: `cd package && bun run test:ci`
- [ ] Tested on iOS (device)
- [ ] Tested on Android (device)
- [ ] Tested in TEST mode
- [ ] Tested in PRODUCTION mode

## Screenshots/Videos
(If applicable)

## Related Issues
Closes #(issue number)

## Breaking Changes
(If any, describe migration path)

Review Process

  • PRs will be reviewed by maintainers
  • Address feedback promptly
  • Keep PRs focused and reasonably sized
  • Be patient and respectful during reviews

What to Contribute

Good First Issues

  • Documentation improvements
  • Bug fixes
  • Type improvements
  • Example app enhancements

Feature Requests

Check the Roadmap for planned features, or open an issue to discuss new features before implementing.

Areas Needing Help

  • Additional payment gateway support
  • Performance optimizations
  • Documentation examples

Reporting Bugs

  1. Check existing issues to avoid duplicates
  2. Use the bug report template
  3. Include:
    • Steps to reproduce
    • Expected vs actual behavior
    • Device/platform information
    • Code snippets if relevant

Questions?

Thank you for contributing to React Native Pay! 🎉