Capacitor 플러그인 기여 가이드

Capacitor 플러그인은 네이티브 장치 기능과 웹 기술을 연결하여 가능합니다. 다양한 플랫폼을 위한 앱 개발. 이 안내서가 도와 줄 것입니다:

• 환경 설정: 필요한 도구들 Node.js, Xcode, 그리고 Android Studio 는 필수입니다.
• Follow Code Standards: TypeScript, Swift, 그리고 Kotlin 일관된 이름 규칙과 오류 처리를 사용하여
• 깊이 테스트하세요: JavaScript, iOS, Android에서 단위 테스트를 작성하여 신뢰성을 보장하세요.
• rõ하게 문서화하세요: JSDoc 및 README 파일을 사용하여 쉽게 수용할 수 있도록 하세요.
• Pull Request 제출: 높은 품질의 code, 테스트, 문서화를 보장하기 전에 기여하세요.

오픈 소스에 대한 완전한 안내서 - 기여 방법

개발 환경 설정

효율적인 플러그인 개발을 위해 개발 환경을 올바르게 설정하는 것이 중요합니다. 잘 준비된 설정은 플러그인의 코드 작성, 테스트, 배포가 순조롭게 진행되도록 합니다.

필요한 도구와 기술

시작하기 전에 다음 도구가 설치되어 있는지 확인하세요.

웹 개발을 위해 TypeScript에 익숙해야 하며 iOS용으로는 Swift, 안드로이드용으로는 Java/Kotlin에 익숙해야 하는 native 개발 작업을 위해 [1][2].

모노레포 설정

The Capacitor 플러그인 이코시스템은 모노레포 구조에 의존합니다. 이 접근 방식은 작업이 커뮤니티 표준과 일치하는지부터 시작하여 작업을 시작할 수 있도록 합니다.

1. 리포지토리 fork 및 클론
   fork 된 Capacitor 플러그인 리포지토리를 GitHub에서 시작하여, fork 된 리포지토리를 클론하세요:

   git clone https://github.com/your-username/capacitor-plugins.git
   cd capacitor-plugins
   npm install

2. 설치 의존성 및 빌드
   Capacitor를 사용하여 모든 필요한 것을 설치하고 플러그인을 빌드하려면 다음 명령어를 실행하세요.

   npm run build

3. 버전 관리 설정
   변경 사항을 관리하기 위해 기능 branch를 사용하고 upstream 저장소와 fork를 동기화하세요.

자연 플랫폼 준비

크로스 플랫폼 개발을 위해 iOS 및 Android 환경을 모두 구성해야 합니다.

iOS:

• Mac App Store에서 Xcode를 다운로드하세요.

• 명령줄 도구를 설치하려면:

  xcode-select --install

• CocoaPods를 다음 명령어로 설치하세요:

  sudo gem install cocoapods

• Apple Developer 계정과 필요한 인증서를 설정하세요.

• code 품질을 유지하기 위해 SwiftLint (선택 사항)을 사용하세요.

안드로이드용:

• SDK과 최신 버전, 가상 장치와 함께 안드로이드 스튜디오를 설치하십시오.
• JDK가 설치되어 있는지 확인하십시오.
• 안드로이드 스튜디오 내에서 SDK를 올바르게 구성하십시오.

이러한 플랫폼을 설정한 후,established coding practices를 따르며 플러그인 개발에 뛰어들 수 있을 것입니다.

Code Standards Guide

개발 환경이 설정되면, 유지보수 및 사용이 쉬운 플러그인을 만들기 위해 이 지침을 따르십시오.

Style Guide Compliance

The Capacitor plugin ecosystem strict coding standards를 강제하는 __CAPGO_KEEP_0__는 ESLint와 같은 도구를 사용합니다. The __CAPGO_KEEP_0__ plugin ecosystem enforces strict coding standards using tools like ESLint, Prettier, 그리고 SwiftLint. 여기서 설명한 내용은 간단한 개요입니다.

TypeScript을 사용하여 더 나은 타입 안전성과 ES6+ 기능을 사용하는 플러그인은 더 나은 성능을 제공합니다. async/awaitSwift (iOS)와 Kotlin (Android)과 같은 플랫폼에 맞는 코딩 규칙을 따르세요.

오류 및 타입 관리

다양한 플랫폼에서 호환성을 유지하기 위해 일관된 오류 처리가 중요합니다. 예를 들어:

async checkPermissions(): Promise<PermissionStatus> {
  try {
    const result = await this.implementation.checkPermissions();
    return result;
  } catch (error) {
    throw new Error(`Permission check failed: ${error.message}`);
  }
}

타입 안전성을 위해:

• 특정 사용 사례에 맞는 집중된 인터페이스를 사용하세요.
• 플랫폼에 맞는 변형을 위한 유니온 타입을 적용하세요.

Code 문서

플러그인이 사용하기 쉬운지 쉽게 사용할 수 있는지 문서화하는 것이 중요합니다. 이 관행을 따르세요:

1. API 문서: JSDoc 주석을 사용하여 __CAPGO_KEEP_0__와 호환되도록 작성하세요. 예를 들어: @capacitor/docgen: __CAPGO_KEEP_0__와 호환되도록 JSDoc 주석을 작성하세요.

/**
 * @description Get the device's current battery level
 * @returns Promise with the battery level percentage
 */
async getBatteryLevel(): Promise<{ level: number }>;

2. README 구조: 설치 방법, 구성 방법, 플랫폼별 요구 사항, 사용 예제 및 자세한 API 참조를 포함하는 정보를 포함합니다.

웹 문서가 잘 작성되어 있으면 플러그인이 쉽게 채택되고 더 광범위한 Capacitor 커뮤니티에 기여할 수 있습니다.

sbb-itb-f9944d2

플러그인 테스트 안내서

Capacitor 플러그인 테스트에는 기능이 smooth하고 신뢰할 수 있도록 하기 위해 몇 가지 중요한 영역에 집중하는 것이 포함됩니다.

네이티브 브리지 테스트

네이티브 브리지 테스트는 자바스크립트와 네이티브 code 간의 올바른 통신을 보장합니다. 시작하려면 각 플랫폼에 맞게 설계된 테스트 환경을 설정하세요.

네이티브 브리지 테스트를 위해 다음 예시를 참조하세요. Jest 자바스크립트 쪽의 단위 테스트 예시입니다.

// Example of a Jest unit test for the JavaScript bridge
describe('DeviceInfo Plugin', () => {
  test('getBatteryLevel returns valid percentage', async () => {
    const result = await DeviceInfo.getBatteryLevel();
    expect(result.level).toBeGreaterThanOrEqual(0);
    expect(result.level).toBeLessThanOrEqual(100);
  });
});

네이티브 쪽 테스트를 위해 iOS에서는 XCTest, Android에서는 JUnit을 사용하세요. Android의 예시는 다음과 같습니다.

@Test
fun testBatteryLevel() {
    val plugin = DeviceInfo()
    val result = plugin.getBatteryLevel()
    assertTrue(result.level in 0..100)
}

기본 브리지 기능이 예상대로 작동하는지 확인한 후, 완전한 사용자 워크플로를 테스트하는 데로 넘어가세요.

완전한 플러그인 테스트

플러그인이 다양한 상황에서 잘 작동하는지 확인하려면, 여러 범주를 테스트하세요:

복잡한 기능을 가진 플러그인의 경우, 실제 사용자 시나리오를 시뮬레이션하세요. 예를 들어, 디바이스 정보 플러그인을 테스트하는 경우, 다음을 확인하세요:

• 다양한 네트워크 조건 하에서 성공적인 업로드
• 정확한 진행 상황 보고
• 대형 파일 전송 중 메모리 사용량

OTA 테스트와 Capgo

Capgo의 오픈 소스 도구는 업데이트를 빠르게 배포하고 테스트하는 것을 쉽게 만듭니다. 사용 방법은 다음과 같습니다.

1. 설정 업데이트 채널 개발, 스테이징, 및 프로덕션과 같은 것들
2. CI/CD 도구를 사용하여 배포를 자동화하세요.
3. 업데이트를 즉시 푸시하세요.
4. 성능 및 문제를 모니터링하는 데 사용하는 Capgo 대시보드.

Capgo은 phased rollouts를 지원하여 업데이트를 작은 사용자 그룹으로 제한할 수 있습니다. 예를 들어, 매일 24시간마다 25%의 사용자에게 새로운 버전을 출시할 수 있습니다.

// Example configuration for staged rollout
{
  "plugin": "camera-plugin",
  "version": "1.2.0",
  "rollout": {
    "percentage": 25,
    "interval": "24h"
  }
}

이 phased 접근법은 커뮤니티 피드백을 활용하여 문제를 일찍 식별할 수 있습니다.

Pull Request Process

변경 사항을 철저히 테스트한 후 다음 단계를 따라서 pull request를 제출하세요:

PR Submission Checklist

제출하기 전에 다음 주요 영역을 확인하세요:

커뮤니티 지침

협업 시 다음의最佳 관행을 따르십시오:

• 리뷰어 피드백에 신속하게 반응하십시오.
• 기술 세부 사항에만 논의하십시오.
• GitHub의 제안 기능을 사용하여 code의 변경을 제안하십시오.
• 작은, 집중된 풀 리퀘스트를 제출하여 한 기능 또는 이슈당 한 번씩 처리하십시오.

큰 변경의 경우, 먼저 이슈를 생성하고 접근 방식을 논의하는 것이 좋습니다. Capacitor 팀은 GitHub Actions를 사용하여 자동화된 확인을 수행하며, 모든 확인이 통과해야 리뷰가 진행될 수 있습니다.

Capgo 통합 가이드

Capgo와 함께 실시간 업데이트를 지원하는 플러그인이면, 제출하기 전에 Capgo가 정상적으로 작동하는지 확인하세요:

1. 버전 관리
   플러그인의 버전 관리를 명확하게 하세요. 모든 변경 사항을 changelog에 기록하고, Capgo의 시스템은 사용자 기기에서 버전을 추적하는 데 도움이 됩니다.

2. CI/CD 통합
   Capgo을 CI/CD pipeline에 통합하여 업데이트 배포를 자동화하세요.

3. 업데이트 모니터링
   배포 성공률을 모니터링하고 앱 스토어 지침을 준수하세요.

요약

플러그인을 통해 의미 있는 기여를 하려면, established 프로세스를 따르고 커뮤니티 표준을 충족해야 합니다. Capacitor의 코딩 가이드라인을 따르고, 플러그인이 실시간 업데이트를 지원하는 경우 Capacitor와 통합하여 업데이트를 빠르게 릴리즈할 수 있습니다.

PR 체크리스트는 높은 품질의 제출이 필요하다는 것을 강조합니다. Capgo와 통합하는 것은 앱 스토어 승인 기다리지 않고 업데이트를 릴리즈할 수 있는 방법입니다.

PR이 병합되면, 이슈를 추적하고 버전 업데이트를 릴리즈하세요. 커뮤니티와의 정기적인 상호작용, 일관된 유지보수, 업데이트를 Capacitor에 따라 지속적으로 유지하는 것은 플러그인을 유용하고 관련성 있는 것으로 유지하는 데 도움이 됩니다.

사용자 피드백에 주의하고 필요에 따라 업데이트를 하세요. 이 지속적인 노력은 생태계의 전체 품질을 유지하고 개발자에게 플러그인이 가치 있는 것을 유지하는 데 도움이 됩니다.