Capacitor 플러그인 기여 가이드

Capacitor 플러그인은 웹 기술과 네이티브 디바이스 기능을 연결하여 크로스 플랫폼 앱 개발을가능하게 합니다. 이 가이드는 다음을 도와줍니다:

• 개발 환경 설정: 다음 도구들 Node.js, Xcode, 그리고 Android Studio 는 필수입니다.
• Code 표준 준수: 다음을 TypeScript, Swift, 그리고 Kotlin 을 일관된 명명 규칙과 에러 핸들링으로 사용하세요.
• 철저한 테스트: 신뢰성을 확보하기 위해 JavaScript, iOS, Android용 유닛 테스트를 작성하세요.
• 명확한 문서화: 사용자가 쉽게 도입할 수 있도록 JSDoc과 README 파일을 활용하세요.
• Pull Request 제출: 기여하기 전에 고품질의 code, 테스트 및 문서화를 완료했는지 확인하세요.

오픈 소스 완벽 가이드 - 기여 방법

개발 환경 설정

효율적인 플러그인 개발을 위해서는 적절한 개발 환경을 구축하는 것이 핵심입니다. 잘 준비된 환경은 플러그인의 원활한 코딩, 테스트 및 배포를 가능하게 합니다.

필요한 도구 및 기술

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

웹 개발을 위한 TypeScript와 네이티브 개발을 위한 Swift(iOS) 또는 Java/Kotlin(Android)에 익숙해야 합니다. [1][2].

모노레포 설정하기

이 Capacitor 플러그인 생태계는 모노레포 구조를 기반으로 합니다. 이 방식을 통해 처음부터 커뮤니티 표준에 맞는 작업을 수행할 수 있습니다.

1. 저장소 Fork 및 Clone
   GitHub에서 Capacitor plugins 저장소를 Fork한 후, 다음 명령어로 Clone하세요:

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

2. 의존성 설치 및 빌드
   다음 명령어를 실행하여 필요한 패키지를 설치하고 플러그인을 빌드하세요:

   npm run build

3. 버전 관리 설정
   변경 사항은 feature branch를 사용하고, Fork한 저장소를 upstream 저장소와 동기화 상태로 유지하세요.

Native 플랫폼 준비하기

크로스 플랫폼 개발을 위해 iOS와 Android 환경을 모두 설정해야 합니다.

iOS의 경우:

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

• 다음 명령어로 command-line tools를 설치하세요:

  xcode-select --install

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

  sudo gem install cocoapods

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

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

Android의 경우:

• Android Studio와 최신 SDK, 가상 디바이스를 설치하세요.
• JDK가 설치되어 있는지 확인하세요.
• Android Studio에서 Android SDK를 올바르게 설정하세요.

플랫폼 설정이 완료되면, 정해진 코딩 관례를 따르며 본격적인 플러그인 개발을 시작할 수 있습니다.

Code 표준 가이드

개발 환경 구축을 마쳤다면, 유지보수와 사용이 용이한 플러그인을 만들기 위해 다음 가이드라인을 준수하세요.

스타일 가이드 준수

the Capacitor 플러그인 생태계는 ESLint, Prettier, ESLint, Prettier및 SwiftLint와 같은 도구를 사용하여 엄격한 코딩 표준을 적용합니다. 필수 포맷팅 요약은 다음과 같습니다:

더 나은 타입 안정성과 ES6+ 기능을 위해 플러그인은 TypeScript를 사용해야 합니다. async/await또한 Swift(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 주석을 작성하세요: @capacitor/docgen예시:

/**
 * @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 플러그인을 테스트할 때는 원활한 기능 작동과 신뢰성을 보장하기 위해 몇 가지 핵심 영역에 집중해야 합니다.

Native Bridge 테스트

Native bridge 테스트는 JavaScript와 native code 간의 통신이 제대로 이루어지는지 확인합니다. 먼저 각 플랫폼에 최적화된 프레임워크로 테스트 환경을 구축하세요.

다음은 JavaScript 측의 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);
  });
});

Native 측 테스트를 위해서는 iOS는 XCTest, Android는 JUnit을 사용하세요. 다음은 Android 예시입니다:

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

핵심 bridge 기능이 예상대로 작동하는 것을 확인했다면, 이제 전체 사용자 워크플로우 테스트로 넘어갑니다.

전체 플러그인 테스트

플러그인이 다양한 시나리오에서 잘 작동하는지 확인하려면 다음 카테고리들을 테스트하세요:

복잡한 기능을 가진 플러그인의 경우, 실제 사용자 시나리오를 시뮬레이션하세요. 예를 들어, DeviceInfo 플러그인을 테스트한다면 다음 사항을 확인해야 합니다:

• 다양한 네트워크 환경에서의 업로드 성공 여부
• 정확한 진행률 보고
• 대용량 파일 전송 중 메모리 사용량

OTA Testing with Capgo

Capgo의 오픈 소스 도구를 사용하면 업데이트를 빠르고 간편하게 배포하고 테스트할 수 있습니다. 사용 방법은 다음과 같습니다:

1. 설정하기 업데이트 채널 dev, staging, production 환경처럼 구성하세요.
2. CI/CD 도구로 배포를 자동화하세요.
3. 업데이트를 즉시 푸시하세요.
4. 다음 도구를 통해 성능과 이슈를 모니터링하세요: Capgo 대시보드.

단계적 배포를 위해, Capgo를 사용하면 업데이트 대상 사용자를 소수 비율로 제한할 수 있습니다. 예를 들어, 24시간마다 사용자 중 25%에게만 새 버전을 배포할 수 있습니다:

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

이러한 단계적 접근 방식은 전체 출시 전 커뮤니티 피드백을 활용하여 문제를 조기에 발견하는 데 도움이 됩니다.

Pull Request 프로세스

변경 사항에 대한 테스트를 모두 마쳤다면, 다음 단계에 따라 pull request를 제출해 주세요:

PR 제출 체크리스트

제출 전, 다음 핵심 사항들을 모두 확인했는지 점검하세요:

커뮤니티 가이드라인

협업 시 다음의 베스트 프랙티스를 준수해 주세요:

• 리뷰어의 피드백에 신속하게 응답하세요.
• 논의는 기술적인 세부 사항에 집중하세요.
• GitHub의 suggestion 기능을 사용하여 code 변경 사항을 제안하세요.
• 한 번에 하나의 기능이나 이슈만 다루는 작고 집중된 pull request를 제출하세요.

규모가 큰 변경 사항은 먼저 issue를 생성하여 접근 방식을 논의하는 것이 좋습니다. Capacitor 팀은 자동화된 체크를 위해 GitHub Actions를 사용하며, pull request가 리뷰되기 전에 모든 체크를 통과해야 합니다.

Capgo 통합 가이드

플러그인에 live updates가 포함된 경우, 제출 전 Capgo와 원활하게 작동하는지 확인하세요:

1. 버전 관리
   플러그인에 명확한 semantic versioning을 사용하고, 모든 변경 사항을 changelog에 기록하세요. Capgo 시스템은 사용자 기기 전반의 버전 채택 현황을 추적하는 데 도움을 줍니다.

2. CI/CD 통합
   업데이트 배포를 자동화하려면 Capgo를 CI/CD 파이프라인에 통합하세요.

3. 업데이트 모니터링
   배포 성공률을 모니터링하고 앱 스토어 가이드라인 준수 여부를 확인하세요.

요약

플러그인으로 의미 있는 기여를 하려면 정해진 프로세스를 따르고 커뮤니티 표준을 충족하는 것이 중요합니다. 여기에는 Capacitor의 코딩 가이드라인 준수와 철저한 테스트가 포함됩니다.

PR 체크리스트는 고품질 제출의 중요성을 강조합니다. 플러그인이 live updates를 지원한다면, (앞서 언급했듯이) Capgo와 통합하여 앱 스토어 승인을 기다리지 않고 빠르게 업데이트를 출시할 수 있습니다.

PR이 머지된 후에도 이슈를 추적하고 버전을 업데이트하며 지속적으로 참여하세요. 커뮤니티와의 꾸준한 소통과 지속적인 유지보수, 그리고 Capacitor 업데이트를 지속적으로 확인하는 것은 플러그인의 유용성과 관련성을 유지하는 데 도움이 됩니다.

사용자 피드백에 주의를 기울이고 필요에 따라 업데이트를 진행하세요. 이러한 지속적인 노력은 생태계 전반의 품질을 유지하고 개발자들에게 플러그인의 가치를 높여줍니다.

Capacitor Plugin Contribution Guide에서 계속하기

사용 중이라면 Capacitor 플러그인 기여 가이드 네이티브 플러그인 작업을 계획하려면, 다음을 연결하세요: Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우는 Capgo 제공 Capacitor Plugins Capacitor Plugins by Capgo의 구현 상세 내용은 플러그인 추가 및 업데이트 Adding or Updating Plugins의 구현 상세 내용은 Ionic Enterprise 플러그인 대안 Ionic Enterprise Plugin Alternatives의 제품 워크플로우와 Capgo Native Build Capgo Native Builds 제품 워크플로우용.