Capacitor 플러그인 기여 안내서

Capacitor 플러그인은 웹 기술과 네이티브 디바이스 기능을 연결하여 네이티브 디바이스 기능을 사용할 수 있게 합니다. 다양한 플랫폼을 지원하는 앱 개발. 이 안내서가 도와 줄 것입니다:

환경 설정: 필요한 도구들 Node.js, Xcode, 그리고 Android Studio 은 필수입니다.
Follow Code Standards: TypeScript, 스위프트, 그리고 코틀린 일관된 이름 규칙과 오류 처리를 사용하여
깊이 테스트하십시오: 자바스크립트, iOS, Android에 대한 단위 테스트를 작성하여 신뢰성을 보장하십시오.
명확하게 문서화하십시오: JSDoc 및 README 파일을 사용하여 쉽게 수용할 수 있도록 하십시오.
Pull Request 제출: 높은 품질의 code, 테스트, 문서화를 보장한 후 기여하십시오.

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

개발 환경 설정

__CAPGO_KEEP_0__

적절한 개발 환경을 구축하는 것은 플러그인 개발의 효율성을 위한 핵심입니다. 잘 준비된 설정은 플러그인의MOOTH한 코딩, 테스트 및 배포를 허용합니다.

필요한 도구 및 기술

시작하기 전에 다음 도구가 설치되어 있는지 확인하십시오.	분류
요구 사항	Node.js (LTS), npm 6+, Git
Node.js (LTS), __CAPGO_KEEP_0__ 6+, Git	Visual Studio Code Visual Studio __CAPGO_KEEP_0__
또는 선호하는 에디터	Xcode, SwiftLint, CocoaPods
안드로이드 개발	Android Studio, 안드로이드 SDK, JDK

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

모노레포 설정

__CAPGO_KEEP_0__ 플러그인 Capacitor plugins 리포지토리 fork 및 클론

__CAPGO_KEEP_0__ 플러그인 리포지토리를 __CAPGO_KEEP_1__에서 fork한 다음, fork한 리포지토리를 클론하세요:
Start by forking the Capacitor plugins repository on GitHub. Then, clone your forked repository:
```
git clone https://github.com/your-username/capacitor-plugins.git
cd capacitor-plugins
npm install
```
설치 의존성 및 빌드
Capacitor, Cloudflare, GitHub, Capgo, code, API, SDK, CLI, npm, bun과 같은 보호 토큰을 제외한 모든 텍스트를 번역합니다.
```
npm run build
```
버전 관리 설정
변경 사항을 관리하고 upstream 저장소와 동기화하기 위해 feature branch를 사용하세요.

자연 플랫폼 준비

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

iOS:

Mac App Store에서 Xcode를 다운로드하세요.
다음 명령어를 사용하여 명령줄 도구를 설치하세요.
```
xcode-select --install
```
CocoaPods를 다음 명령어로 설치하세요.
```
sudo gem install cocoapods
```
Apple Developer 계정과 필요한 인증서를 설정하세요.
SwiftLint (선택 사항)을 사용하여 code 품질을 유지하세요.

For Android:

Android Studio와 최신 SDK 및 가상 장치와 함께 설치하십시오.
JDK가 설치되어 있는지 확인하십시오.
Android Studio 내에서 Android SDK를 올바르게 구성하십시오.

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

Code Standards Guide

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

Style Guide Compliance

__CAPGO_KEEP_0__ plugin ecosystem Capacitor plugin ecosystem ESLint The __CAPGO_KEEP_0__ plugin ecosystem enforces strict coding standards using tools like ESLint, Prettier, SwiftLint을 포함하여. 여기서 formatting에 대한 빠른 개요입니다.

Component	형식
변수	`deviceInfo` (camelCase)
클래스	`BatteryManager` (PascalCase)
메소드	`getLanguageCode()` (camelCase)
상수	`MAX_RETRY_COUNT` (SNAKE_CASE)

플러그인은 TypeScript를 사용하여 더 나은 타입 안전성과 ES6+ 기능을 사용해야 합니다. 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 문서

좋은 문서는 플러그인을 사용하기 쉽고 접근하기 쉬운 것입니다. 다음의 관행을 따르세요:

API 문서: JSDoc 주석을 사용하여 @capacitor/docgen. 예를 들어:

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

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 Live Update 대시보드 인터페이스

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

설정 업데이트 채널 개발, 스테이징, 및 프로덕션과 같은 채널
CI/CD 도구를 사용하여 배포를 자동화합니다.
업데이트를 즉시 푸시합니다.
성능 및 문제를 모니터링하는 데 사용하는 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

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

Category	체크해야 할 사항
Code 품질	- Swift/Kotlin 구현이 웹 API와 일치하는지 확인하세요.
테스트	- 새로운 기능에 대한 단위 테스트를 추가합니다. - CI/CD pipeline 확인이 성공적으로 완료되는지 확인합니다.
문서화	- README, 인라인 문서, CHANGELOG를 필요에 따라 업데이트합니다.

커뮤니티 지침

협업 시 다음의 최선의 관행을 따릅니다:

리뷰어 피드백에 신속하게 반응합니다.
기술 세부 사항에만 논의합니다.
GitHub의 제안 기능을 사용하여 code의 변경 사항을 제안합니다.
작은, 집중된 풀 요청을 제출하여 한 기능 또는 문제에 대해 한 번에 처리합니다.

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

Capgo Integration Guide

Capgo이 포함된 플러그인이 실시간 업데이트를 지원하는 경우, 제출하기 전에 Capgo과 완벽하게 호환되는지 확인하세요:

버전 관리
플러그인의 버전을 명확하게 의미하는 버전으로 관리하고, 모든 변경 사항을 changelog에 문서화하세요. Capgo의 시스템은 사용자 기기의 버전 수용률을 추적하는 데 도움이 됩니다.
CI/CD 통합
Capgo을 CI/CD pipeline에 통합하여 업데이트 배포를 자동화하세요.
업데이트 모니터링
배포 성공률을 모니터링하고 앱 스토어 지침을 준수하세요.

요약

플러그인을 통해 의미 있는 기여를 하려면 established 프로세스를 따르고 커뮤니티 표준을 충족해야 합니다. 이에는 Capacitor의 코딩 가이드라인을 따르고, 작업을 철저히 테스트하는 것이 포함됩니다.

Capgo과 통합하여 (이전 섹션에서 언급한 것처럼) 실시간 업데이트를 지원하는 플러그인이 있는 경우, 앱 스토어 승인 대기 없이 업데이트를 빠르게 릴리스할 수 있습니다.

PR 체크리스트는 고품질의 제출이 필요하다는 것을 강조합니다. PR이 병합된 후, 이슈를 추적하고 버전 업데이트를 릴리스하세요. 커뮤니티와의 정기적인 상호작용, 일관된 유지보수, 업데이트를 Capacitor에 따라 지속적으로 유지하는 것은 플러그인을 유용하고 관련성 있는 것으로 유지하는 것을 보장합니다.

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

Capacitor 플러그인 기여 가이드에서 계속 진행하세요.

__CAPGO_KEEP_0__ 플러그인 기여 가이드를 사용하여 자연 플러그인 작업을 계획하고 Capacitor 플러그인 디렉토리와 연결하세요. __CAPGO_KEEP_0__ 플러그인 디렉토리에서 Capgo 플러그인들에 의해 __CAPGO_KEEP_1__ Capgo 플러그인들에 의해 __CAPGO_KEEP_1__에서 Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, __CAPGO_KEEP_1__ 구현 세부 정보에 대한 추가 또는 업데이트 플러그인에 대해 Ionic Enterprise 플러그인 대체 Ionic Enterprise 플러그인 대체에 대한 제품 워크플로우 Capgo 네이티브 빌드 Capgo 네이티브 빌드에 대한 제품 워크플로우