Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
321 lines (235 loc) · 7 KB

CONTRIBUTING.md

File metadata and controls

321 lines (235 loc) · 7 KB

Contributing to SmartCard

Thank you for your interest in contributing to SmartCard! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to uphold this code. Please:

  • Be respectful and constructive in discussions
  • Welcome newcomers and help them get started
  • Focus on what is best for the community
  • Show empathy towards other community members

Please report unacceptable behavior by opening an issue with the conduct label.

Getting Started

Prerequisites

  • macOS 14.0 or later
  • Xcode 15.0 or later
  • iOS 17.0+ simulator or device
  • Git

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/SmartCard.git
cd SmartCard
  3. Add the upstream repository: 
    git remote add upstream https://github.com/Rich627/SmartCard.git

How to Contribute

Types of Contributions

Type Description
Bug Fixes Fix issues and improve stability
Features Add new functionality
Documentation Improve README, comments, guides
Localization Add/improve translations
Tests Add or improve test coverage
UI/UX Improve design and user experience
Card Data Add new credit card definitions

Good First Issues

Look for issues labeled good first issue - these are great for newcomers!

Development Setup

  1. Open the project

    open SmartCard.xcodeproj

  2. Select a simulator

    • Choose iPhone 15 or newer simulator
    • Or connect a physical device

  3. Build and run

    • Press ⌘ + R to build and run
    • Press ⌘ + U to run tests

Project Structure

SmartCard/
├── App/           # App entry point
├── Models/        # Data models (Card, Spending, etc.)
├── Views/         # SwiftUI views
├── ViewModels/    # State management
├── Services/      # Business logic
└── Utils/         # Helper extensions

Coding Standards

Swift Style Guide

  • Follow Swift API Design Guidelines
  • Use meaningful variable and function names
  • Keep functions small and focused
  • Add comments for complex logic

SwiftUI Best Practices

// Good: Small, focused views
struct CardRowView: View {
    let card: CreditCard

    var body: some View {
        HStack {
            CardIconView(card: card)
            CardInfoView(card: card)
        }
    }
}

// Avoid: Large, monolithic views
struct CardRowView: View {
    var body: some View {
        // 200+ lines of code...
    }
}

Naming Conventions

Type Convention Example
Types UpperCamelCase CreditCard, SpendingCategory
Functions lowerCamelCase calculateReward(), fetchCards()
Variables lowerCamelCase selectedCard, totalSpending
Constants lowerCamelCase maxCards, defaultReward

File Organization

// MARK: - Properties
// MARK: - Initialization
// MARK: - Body (for Views)
// MARK: - Private Methods
// MARK: - Static Methods

Pull Request Process

Before Submitting

  • Code compiles without warnings
  • All tests pass (⌘ + U)
  • New code has appropriate tests
  • Code follows project style guidelines
  • Documentation updated if needed

PR Checklist

  1. Create a feature branch

    git checkout -b feature/your-feature-name

  2. Make your changes

    • Write clean, documented code
    • Add tests for new functionality
    • Update documentation if needed

  3. Commit with clear messages

    git commit -m "Add: credit card sorting by reward rate"
git commit -m "Fix: rotating category activation bug"
git commit -m "Update: README installation instructions"

  4. Push and create PR

    git push origin feature/your-feature-name

    Then open a Pull Request on GitHub.

PR Title Format

[Type] Brief description

Types:
- Add: New feature
- Fix: Bug fix
- Update: Enhancement to existing feature
- Remove: Removing code/feature
- Refactor: Code restructuring
- Docs: Documentation only
- Test: Adding tests

Review Process

  1. A maintainer will be automatically assigned via CODEOWNERS
  2. At least 1 maintainer review is required before merging
  3. All CI checks must pass (build, tests, SwiftLint, scraper validation)
  4. Address any requested changes and re-request review
  5. Once approved and CI is green, your PR will be merged

Reporting Bugs

Before Reporting

  • Check existing issues to avoid duplicates
  • Try to reproduce with the latest version

Bug Report Template

**Description**
A clear description of the bug.

**Steps to Reproduce**
1. Go to '...'
2. Tap on '...'
3. See error

**Expected Behavior**
What should happen.

**Actual Behavior**
What actually happens.

**Screenshots**
If applicable.

**Environment**
- iOS Version:
- Device:
- App Version:

Suggesting Features

Feature Request Template

**Problem**
What problem does this solve?

**Proposed Solution**
How should it work?

**Alternatives Considered**
Other solutions you've thought about.

**Additional Context**
Mockups, examples, etc.

Adding Credit Card Data

Credit card data is managed through the scraper system in Functions/scraper/.

Option 1: Add to Existing Scraper

  1. Open the appropriate scraper in Functions/scraper/scrapers/ (e.g., chase.js, amex.js)
  2. Add the card to the CARDS array:
{
  name: 'Card Name',
  annualFee: 0,
  rewardType: 'cashback',  // 'cashback', 'points', or 'miles'
  network: 'visa',         // 'visa', 'mastercard', 'amex', 'discover'
  baseReward: 1,
  categories: [
    { category: 'dining', multiplier: 3, cap: 1500, capPeriod: 'quarterly' }
  ],
  imageURL: 'https://...',
  imageColor: '#1A1A1A'
}
  1. Run the scraper and upload:
cd Functions/scraper
npm run full  # Scrapes all cards and uploads to Firestore

Option 2: Add New Issuer

  1. Create a new scraper file in Functions/scraper/scrapers/
  2. Extend BaseScraper class (see existing scrapers for examples)
  3. Register it in Functions/scraper/index.js

Verification

  • Verify card data accuracy from official issuer websites
  • Run npm run validate to check data format
  • Test in the iOS app after uploading

Questions?

Feel free to open an issue with the question label or reach out to the maintainers.

Thank you for contributing!