Contributing Guide

Contributing to LibDC-Swift

Development Setup

Prerequisites

• Xcode 15.0+
• Swift 5.10+
• iOS 15.0+ / macOS 12.0+
• Git
• libdivecomputer (for C library development)

Environment Setup

1. Clone the Repository

git clone https://github.com/latishab/LibDC-Swift.git
cd LibDC-Swift

2. Open Project

open Package.swift

Building

1. Command Line

swift build
swift test

2. Xcode

• Open Package.swift
• Select your target device/simulator
• Build (⌘B)

Coding Standards

Swift Style Guide

1. Naming

// Types: UpperCamelCase
struct DiveProfile { }
class DiveComputer { }
enum ConnectionState { }

// Variables/Functions: lowerCamelCase
var deviceName: String
func connectToDevice() { }

// Constants
let MaxDepth = 100.0

2. Documentation

/// Manages BLE communication with dive computers
///
/// Handles device discovery, connection, and data transfer.
/// - Important: Must be initialized before use
class BLEManager {
    /// Attempts to connect to a dive computer
    /// - Parameters:
    ///   - address: The device's UUID string
    /// - Returns: True if connection was successful
    func connect(address: String) -> Bool {
        // Implementation
    }
}

3. Code Organization

// MARK: - Properties
// MARK: - Initialization
// MARK: - Public Methods
// MARK: - Private Methods
// MARK: - Protocol Conformance
// MARK: - Helper Methods

Best Practices

1. Error Handling

enum DeviceError: Error {
    case connectionFailed(String)
    case invalidData
}

func process() throws {
    guard isValid else {
        throw DeviceError.invalidData
    }
}

2. Memory Management

// Prefer value types when possible
struct DiveData {
    let profile: [ProfilePoint]
}

// Use weak references to avoid retain cycles
weak var delegate: DeviceDelegate?

3. Threading

// Use appropriate queues
DispatchQueue.main.async {
    // UI updates
}

DispatchQueue.global(qos: .userInitiated).async {
    // Background processing
}

Pull Request Process

1. Branch Naming

feature/new-feature-name
bugfix/issue-description
improvement/enhancement-description

2. Commit Messages

feat: Add support for new dive computer model
fix: Resolve connection timeout issue
docs: Update installation instructions
test: Add test cases for parser
refactor: Improve error handling

3. PR Template

## Description
Brief description of changes

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

## Testing
Description of testing performed

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guide
- [ ] All tests passing

Testing Guidelines

Unit Tests

1. Test Structure

import XCTest
@testable import LibDCSwift

final class ParserTests: XCTestCase {
    var parser: DiveParser!
    
    override func setUp() {
        super.setUp()
        parser = DiveParser()
    }
    
    override func tearDown() {
        parser = nil
        super.tearDown()
    }
    
    func testParsingValidData() {
        // Test implementation
    }
}

2. Test Coverage

• Aim for 80%+ coverage
• Cover edge cases
• Test error conditions
• Include performance tests

3. Mock Objects

class MockBLEDevice: BLEDeviceProtocol {
    var connectCalled = false
    
    func connect() -> Bool {
        connectCalled = true
        return true
    }
}

Integration Tests

1. Device Communication

func testDeviceCommunication() async throws {
    let device = try await connectToDevice()
    let logs = try await device.retrieveLogs()
    XCTAssertFalse(logs.isEmpty)
}

2. End-to-End Tests

func testCompleteDownloadFlow() async throws {
    // 1. Connect
    // 2. Download
    // 3. Parse
    // 4. Verify
}

Performance Tests

func testParsingPerformance() {
    measure {
        // Code to measure
    }
}

Release Process

1. Version Bump

• Update version in Package.swift
• Update changelog
• Create release notes

2. Testing

• Run full test suite
• Perform manual testing
• Check documentation

3. Release

• Create tag
• Push release
• Update documentation

Getting Help

• Check existing issues
• Join discussions
• Review documentation
• Contact maintainers

Remember to:

• Be respectful
• Follow code of conduct
• Write clear issues/PRs
• Help others