코드 기여하기

메이저 버전 출시에 대한 자세한 내용은 버전 정책을 참고하세요.

호환성은 다음과 같이 유지하세요:

• 안정적인 인터페이스 (항상 보존): 함수 시그니처와 파라미터 이름, 클래스 인터페이스와 메서드 이름, 반환 값 구조와 타입, 공개 API의 임포트 경로
• 안전한 변경 (허용되는 수정): 새 선택적 파라미터/타입 파라미터 추가, 클래스에 새 메서드 추가, 동작 변경 없이 성능 개선, 새 모듈이나 함수 추가
• 변경 전 확인: 기존 사용자 코드를 깨뜨리지 않는가? 대상이 공개 API인가? 테스트에 기존 사용 패턴이 있는가?

새 기능 (New features)

새 기능에 대한 기준을 높게 유지하려고 합니다. 긴급한 필요를 보여주는 기존 이슈 없이는 외부 기여자의 새로운 핵심 추상화는 일반적으로 받지 않습니다. 이는 인프라와 의존성 변경에도 적용됩니다.

일반적으로 기능 기여 요건은 다음과 같습니다:

1. 설계 논의 — 다음을 설명하는 이슈를 열기: 해결하려는 문제, 제안하는 API 설계, 기대 사용 패턴
2. 구현 — 기존 코드 패턴 따르기, 포괄적인 테스트와 문서 포함, 보안 영향 고려
3. 통합 고려 사항 — 기존 기능과 어떻게 상호작용하는가? 성능 영향이 있는가? 새 의존성을 도입하는가?

보안 취약점이나 보고로 이어질 가능성이 있는 기능은 거부할 것입니다.

보안 지침 (Security guidelines)

보안 체크리스트:

• 입력 검증: 모든 사용자 입력을 검증하고 살균하며, 템플릿과 쿼리에서 데이터를 적절히 이스케이프하고, 임의 코드 실행 취약점으로 이어질 수 있는 eval()을 절대 사용하지 않기
• 오류 처리: 특정 예외 유형 사용, 오류 메시지에 민감한 정보 노출 금지, 적절한 리소스 정리 구현
• 의존성: 하드 의존성 추가 피하기, 선택적 의존성 최소화, 보안 이슈에 대한 타사 패키지 검토

개발 환경 (Development environment)

pnpm install
pnpm --filter {package-name} test  # Verify tests pass before starting development

기여 지침을 검토한 후, 아래 저장소 구조 섹션에서 작업 중인 컴포넌트의 패키지 디렉터리를 찾으세요.

저장소 구조 (Repository structure)

LangChain — LangChain은 여러 패키지를 포함한 모노레포로 구성됩니다:

• 핵심 패키지:
  • langchain (libs/langchain/에 위치): 체인, 에이전트, 검색 로직을 포함한 메인 패키지
  • @langchain/core (libs/langchain-core/에 위치): 기본 인터페이스와 핵심 추상화
• 파트너 패키지 — libs/providers/에 위치하며, 특정 통합을 위한 독립적으로 버전 관리되는 패키지:
  • @langchain/openai: OpenAI 통합
  • @langchain/anthropic: Anthropic 통합
  • @langchain/google: Google 통합
• 지원 패키지:
  • @langchain/textsplitters: 텍스트 분할 유틸리티
  • @langchain/standard-tests: 통합을 위한 표준 테스트 스위트
  • @langchain/community: 커뮤니티 유지 통합 (별도 저장소)

LangGraph — LangGraph는 여러 Python 패키지를 포함한 모노레포로 구성됩니다:

• 핵심 패키지:
  • langgraph (libs/langgraph/에 위치): 상태 유지, 다중 에이전트 에이전트 구축용 핵심 프레임워크
  • langgraph-prebuilt (libs/prebuilt/에 위치): 에이전트와 도구 생성/실행을 위한 고수준 API
• 체크포인트 패키지:
  • langgraph-checkpoint (libs/checkpoint/에 위치): 체크포인트 세이버의 기본 인터페이스
  • langgraph-checkpoint-postgres (libs/checkpoint-postgres/에 위치): Postgres 구현
  • langgraph-checkpoint-sqlite (libs/checkpoint-sqlite/에 위치): SQLite 구현
• SDK 및 CLI:
  • langgraph-sdk (libs/sdk-py/에 위치): Agent Server API용 Python SDK
  • langgraph-cli (libs/cli/에 위치): 공식 커맨드라인 인터페이스

Deep Agents — Deep Agents는 여러 Python 패키지를 포함한 모노레포로 구성됩니다:

• 핵심 패키지:
  • deepagents (libs/deepagents/에 위치): 계획, 파일 시스템, 서브에이전트 기능을 갖춘 딥 에이전트 구축용 핵심 프레임워크
  • deepagents-code (libs/code/에 위치): Deep Agents Code — 대화 재개, 웹 검색, 샌드박스를 갖춘 대화형 터미널 인터페이스
  • deepagents-cli (libs/cli/에 위치): 에이전트를 LangSmith Deployments로 배포하는 배포 도구 (deepagents deploy, deepagents init, deepagents dev)
• 통합 패키지:
  • deepagents-evals (libs/evals/에 위치): LangSmith 트레이싱과 함께하는 평가 스위트 및 Harbor 통합
  • deepagents-acp (libs/acp/에 위치): Agent Client Protocol 통합

개발 워크플로 (Development workflow)

테스트 실행하기

가능하면 통합 테스트보다 단위 테스트를 선호합니다. 단위 테스트는 모든 풀 리퀘스트에서 실행되므로 빠르고 신뢰할 수 있어야 합니다. 통합 테스트는 스케줄에 따라 실행되며 더 많은 설정이 필요하므로, 외부 서비스와의 인터페이스 지점을 확인하는 데만 사용해야 합니다.

단위 테스트 (Unit tests)

위치: src/tests/FILENAME_BEING_TESTED.test.ts

단위 테스트는 외부 API 호출이 필요 없는 모듈형 로직을 다룹니다. 새 로직을 추가하면 단위 테스트를 추가해야 합니다. 단위 테스트에서는 전/후 처리를 확인하고 외부 의존성을 목(mock)처리합니다.

요건:

• 네트워크 호출 금지
• 엣지 케이스를 포함한 모든 코드 경로 테스트
• 외부 의존성에 목 사용

# Run the entire test suite
pnpm test

# Or run a specific test file
pnpm test src/tests/FILENAME_BEING_TESTED.test.ts

# Or run a specific test function
pnpm test -t "the test that should be run"

통합 테스트 (Integration tests)

위치: src/tests/FILENAME_BEING_TESTED.int.test.ts

통합 테스트는 외부 API 호출(종종 다른 서비스와의 통합)이 필요한 로직을 다룹니다.

통합 테스트는 외부 서비스/프로바이더 API 접근(비용이 들 수 있음)이 필요하므로 기본적으로 실행되지 않습니다.

모든 코드 변경에 통합 테스트가 필요한 것은 아니지만, 리뷰 과정의 일부로 통합 테스트를 별도로 요구/실행할 것임을 유의하세요.

요건:

• 외부 서비스와의 실제 통합 테스트
• API 키에 환경 변수 사용
• 자격 증명이 없으면 우아하게 건너뛰기

pnpm test:int

코드 품질 기준 (Code quality standards)

기여는 다음 품질 요건을 준수해야 합니다:

• 타입 힌트 (필수): 모든 함수에 완전한 타입

function processDocuments(
    docs: Document[],
    processor: DocumentProcessor,
    batchSize: number = 100
): ProcessingResult {
    // ...
}

• 문서화 (필수): 모든 내보낸 함수와 인터페이스에 JSDocs

/**
 * Document processing instance.
 */
interface FooDocumentProcessor {
    /**
     * Process documents in batches.
     *
     * @param docs - List of documents to process.
     * @returns Processing results with success/failure counts.
     */
    process(docs: Document[]): ProcessingResult;
}

/**
 * Process documents in batches.
 *
 * @param docs - List of documents to process.
 * @param processor - Document processing instance.
 * @param batchSize - Number of documents per batch.
 * @returns Processing results with success/failure counts.
 */
export function processDocuments(
    docs: Document[],
    processor: DocumentProcessor,
    batchSize: number = 100
): ProcessingResult {
    // ...
}

• 코드 스타일 (자동화): 포맷팅과 린팅

pnpm lint    # Check style and types
pnpm format  # Apply formatting

표준: 설명적인 변수 이름, 복잡한 함수 분해(20줄 미만 목표), 코드베이스의 기존 패턴 따르기

테스트 작성 지침 (Test writing guidelines)

효과적인 테스트를 작성하려면 몇 가지 모범 사례를 따르세요:

• 테스트를 테스트 중인 컴포넌트를 설명하는 describe 블록으로 감싸기
• 테스트 이름을 자연어로 설명하기
• 어서션(assertion)을 철저히 하기
• 합리적인 크기의 데이터 객체에만 스냅샷 사용하기

describe("DocumentProcessor", () => {
    it("Should handle empty document list", () => {
        const processor = new DocumentProcessor();
        const result = processor.process([]);

        expect(result.success).toBe(true);
        expect(result.processedCount).toBe(0);
        expect(result.errors).toHaveLength(0);
    });
});

describe("ChatOpenAI", () => {
    it("Should test with real API", () => {
        const chat = new ChatOpenAI();
        const response = chat.invoke("Hello");
    });
});

describe("APIService", () => {
    it("Should call with retry", () => {
        const mockClient = new MockClient();
        const service = new APIService(client: mockClient);
        const result = service.callWithRetry();
    });
});

PR 제출하기 (Submitting your PR)

테스트가 통과하고 코드가 품질 기준을 충족하면:

1. 브랜치를 푸시하고 풀 리퀘스트를 엽니다
2. 제공된 PR 템플릿을 따릅니다
3. closing keyword(예: Fixes #123)로 관련 이슈를 참조합니다
4. CI 검사가 완료될 때까지 기다립니다

도움 받기 (Getting help)

목표는 가장 접근하기 쉬운 개발자 설정을 갖추는 것입니다. 설정에 어려움이 있다면 커뮤니티 슬랙에 질문하거나 포럼 게시글을 열어주세요.

더 알아보기

• 이 문서를 MCP로 연결하면 Claude, VSCode 등에서 실시간 답변을 받을 수 있어요.
• GitHub에서 이 페이지 편집하기 또는 이슈 제출하기.