Capacitor 플러그인 기여 가이드

Capacitor 플러그인은 웹 기술을 원시 장치 기능과 연결하여 다양한 플랫폼 앱 개발을 가능하게합니다.이 가이드는 다음과 같은 것을 도와줍니다.

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

오픈 소스에 대한 완전한 가이드 - 기여 방법

개발 환경 설정

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

필요한 도구 및 기술

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

웹 개발에 대한 TypeScript에 대한 편안함을 가지고 있어야 하며 iOS (iOS) 또는 Java / Kotlin (Android)로 native 개발 작업을 위해 각각 Swift 또는 Java / Kotlin을 이해해야 합니다. [1][2].

모노레포 설정

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

1. 리포지토리 fork 및 클론
   리포지토리 Capacitor 플러그인을 GitHub에서 fork하고, 클론한 후 fork한 리포지토리를 클론하세요.

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

2. 설치 및 빌드
   모든 것을 설치하고 플러그인을 빌드하려면 다음 명령어를 실행하세요.

   npm run build

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

네이티브 플랫폼 준비

다양한 플랫폼 개발을 위해 iOS 및 Android 환경을 구성해야 합니다.

iOS:

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

• 다음 명령어를 사용하여 명령줄 도구를 설치하세요.

  xcode-select --install

• 다음 명령어를 사용하여 CocoaPods를 설치하세요.

  sudo gem install cocoapods

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

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

Android:

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

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

Code 표준 가이드

개발 환경이 설정되면 이제는 이 가이드라인을 따르세요. 유지보수와 사용이 쉬운 플러그인을 만들기 위해.

스타일 가이드 준수

The Capacitor 플러그인 생태계 strict한 코딩 표준을 지키기 위해 ESLint, Prettier, SwiftLint와 같은 도구를 사용합니다. 다음은 필수 포맷팅에 대한 간단한 개요입니다. Component, Format변수

플러그인은 TypeScript를 사용하여 더 나은 타입 안전성과 ES6+ 기능을 사용하여야 합니다. 또한 Swift (iOS) 및 Kotlin (Android)과 같은 플랫폼에 맞는 코딩 컨벤션을 따르세요. async/await오류 및 타입 관리

교차 플랫폼 호환성을 위해 일관된 오류 처리가 중요합니다. 예를 들어:

타입 안전성에 대한 경우:

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

__CAPGO_KEEP_0__

• 사용자 지정 인터페이스를 사용하여 특정 사용 사례에 맞게 맞춤화합니다.
• 플랫폼에 따라 변형된 union 타입을 적용합니다.

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 Tests

JavaScript와 Native code 사이의 올바른 통신을 보장하기 위해 Native Bridge 테스트를 진행합니다. 시작하기 위해서는 각 플랫폼에 맞는 프레임워크로 테스트 환경을 설정하세요.

예를 들어, Jest JavaScript 측의 단위 테스트 예제입니다.

// 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)
}

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

Complete Plugin Tests

플러그인이 다양한 시나리오에서 잘 동작하는지 확인하기 위해 다양한 카테고리를 테스트하세요.

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

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

__CAPGO_KEEP_0__ Capgo

Capgo’s open-source tools make it easy to deploy and test updates quickly. Here’s how to use it:

1. 설정 업데이트 채널 개발, 스테이징, 및 운영 채널과 같은
2. CI/CD 도구를 사용하여 배포를 자동화합니다.
3. 즉시 업데이트
4. 성능 및 문제를 모니터링하는 Capgo dashboard.

For phased rollouts, Capgo allows you to limit updates to a small percentage of users. For instance, you can roll out a new version to 25% of users every 24 hours:

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

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

Pull Request 프로세스

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

PR 제출 확인 목록

제출하기 전에 다음 주요 영역을 모두 확인하십시오:

커뮤니티 지침

협업 시 다음最佳 관행을 따르세요:

• 리뷰어의 피드백에 신속하게 반응하세요.
• 기술적 세부 사항에만 집중하세요.
• GitHub의 제안 기능을 사용하여 code 변경 사항을 제안하세요.
• 작은, 집중된 풀 리퀘스트를 제출하여 하나의 기능 또는 문제를 처리하세요.

큰 변경 사항의 경우, 먼저 이슈를 생성하고 접근 방식을 논의하세요. Capacitor 팀은 GitHub 액션을 사용하여 자동화 된 확인을 의존하고, 모든 확인이 통과해야 풀 리퀘스트가 검토될 수 있습니다.

Capgo 통합 안내서

라이브 업데이트가 포함된 플러그인인 경우, Capgo에 제출하기 전에 무결성을 보장하세요:

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

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

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

요약

Capacitor의 코딩 가이드라인을 따르고 철저히 테스트한 작업을 제출하는 것은 플러그인으로 의미 있는 기여를 하기 위한 필수입니다. 플러그인이 라이브 업데이트를 지원하는 경우 Capacitor와 통합하면 앱 스토어 승인 대기 없이 빠르게 업데이트를 릴리즈할 수 있습니다.

PR 체크리스트는 높은 품질의 제출이 필요하다는 것을 강조합니다. PR이 병합되면 이슈를 추적하고 버전 업데이트를 릴리즈하세요. 개발자 커뮤니티와의 지속적인 상호작용, 일관된 유지보수, Capgo 업데이트에 대한 지속적인 관심은 플러그인이 유용하고 관련성이 유지되도록 합니다.

사용자 피드백에 주의를 기울이고 필요에 따라 업데이트를 진행하세요. 이 지속적인 노력은 생태계의 전체 품질을 유지하고 개발자에게 플러그인이 가치 있는 것을 유지합니다. keeping up with Capacitor updates Martin Donadieu

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