Skip to main content

Introducing API History (GSoC 2024)

· 12 min read
piotrpdev
piotrpdev

Electron API의 역사적 변경 사항이 이제 문서에 상세히 기록된다.

안녕하세요 👋, 저는 2024년 Google Summer of Code(GSoC)에 참여하여 Electron에 기여한 Peter입니다.

GSoC 프로그램 기간 동안, 저는 Node.js 문서와 유사한 방식으로 Electron 문서와 그 기능, 클래스 등에 대한 API 기록 기능을 구현했다. 이를 위해 API 문서 마크다운 파일에 간단하지만 강력한 YAML 스키마를 사용할 수 있게 했고, Electron 문서 웹사이트에서 이를 멋지게 표시하도록 했다.

세부 사항​

API 히스토리 문서화 시스템 / YAML 스키마​

Markdown API 문서에서 함수, 클래스 등의 히스토리는 해당 항목의 헤더 바로 아래에 위치한다. 이 히스토리는 HTML 주석으로 감싸진 YAML 코드 블록 형태로 작성된다.

#### `win.setTrafficLightPosition(position)` _macOS_

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/22533
changes:
  - pr-url: https://github.com/electron/electron/pull/26789
    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37094
    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->

* `position` [Point](structures/point.md)

트래픽 라이트 버튼의 커스텀 위치를 설정한다. `titleBarStyle`이 `hidden`으로 설정된 경우에만 사용할 수 있다.

Node.js 문서에서 사용하는 YAML 방식을 차용한 이유는 가독성이 좋기 때문이다. API 히스토리는 복잡하지 않아야 하며, 가능한 한 쉽게 작성하고 읽을 수 있어야 한다.

위에 보이는 최종 디자인은 내가 제안한 것과 상당히 다르다:

<!--
```YAML history
added: v10.0.0
deprecated: v25.0.0
removed: v28.0.0
changes:
  - version: v13.0.0
    pr-url: https://github.com/electron/electron/pull/26789
    description: Made `trafficLightPosition` option work for `customButtonOnHover` window.
```
-->

한 가지 큰 변경 사항은 버전 번호를 제거한 것이다:

"[...] 제안을 검토하는 과정에서 나온 중요한 변경 사항이 있다. [...]

[우리는] 버전 문자열을 하드코딩하는 대신 PR URL(메인 브랜치의 루트 PR)만 사용하는 것이 가장 단점이 적은 방법이라고 결정했다.

이 방식은 단일 진실 공급원으로 사용될 수 있으며, 정확한 버전 번호를 도출하는 데 활용할 수 있다. 또한 변경 사항이 다른 브랜치로 백포트되더라도 메인 브랜치의 문서를 추가로 수정할 필요가 없다."

— David Sanders (@dsanders11), Slack에서

또한 API 히스토리에서 제거 사항을 포함하지 않기로 했다. Electron에서 API가 제거되면 문서에서도 함께 제거되기 때문이다.

JavaScript 구현​

원래는 @electron/docs-api-history-tools라는 새로운 npm 패키지를 만들어, 문서 파일에서 API 이력을 추출하고 검증/린팅하며 변환하는 스크립트를 포함할 계획이었다. 하지만 코딩 기간이 시작되기 약 일주일 전, 멘토들과 논의를 거친 후 이 방법이 불필요할 수 있다는 결론에 도달했다.

"안녕하세요, 회의 후 프로젝트에 대해 생각해봤는데요: e/website와 e/lint-roller에서 의존성이 다르기 때문에 추출 로직을 다르게 처리해야 한다면, API 이력 관련 작업을 위한 별도의 패키지가 필요 없을 것 같습니다."

원안수정안
원안수정안

— Piotr Płaczek (나) via Slack

결국 원래 아이디어를 진행하지 않기로 결정했다:

"@Piotr Płaczek 그렇게 하는 것도 괜찮을 것 같아요! 나중에 두 구현 사이에서 많은 코드를 공유해야 한다면 그때 별도의 모듈로 리팩토링할 수도 있을 거예요 🙂"

— Erick Zhao (@erickzhao) via Slack

대신, 각 도구를 가장 관련 있는 Electron 저장소로 분배했다:

Electron 문서 웹사이트 UI 및 스타일링​

원래 API 기록 데이터를 표시하기 위해 간단한 테이블을 제안했었다:

디자인 프로토타입 (닫힘)디자인 프로토타입 (열림)
demo1demo2

이것이 최종 구현된 디자인이다:

demo3

프로토타입과 거의 동일하다. 가장 중요한 추가 사항은 SemVer 범위를 사용한 것이다. 이는 특정 기능이 어떤 버전에 있는지 더 명확히 전달하기 위해 선택했다 (Samuel Attard (@MarshallOfSound)의 제안에 감사한다!).

이것은 변경 사항이 지원되는 Electron 릴리스 라인에 자주 백포트되기 때문에 중요하다. 예를 들어, 수정 사항이 Electron v32.0.0, v31.1.0 및 v30.2.0에 포함될 수 있다. 이는 사용자가 v30.x.x 릴리스에 있다는 사실만으로 v31.0.0에도 포함되어 있다고 잘못 추론할 수 있기 때문이다.

사용/스타일 가이드​

새로운 기능에 대한 API 기록 문서 작성을 위한 전용 사용/스타일 가이드를 추가했다. YAML 스키마의 적절한 사용법을 상세히 설명하고, 일반적이고 유용한 예제를 제공했다. 해당 가이드는 여기에서 확인할 수 있다.

마이그레이션 가이드​

기존 API를 새로운 문서 시스템으로 옮기기 위해 마이그레이션 가이드를 만들었다. 이 가이드는 개발자가 기존 API를 마이그레이션할 때 일반적으로 거쳐야 하는 단계를 다룬다. 주요 변경 사항을 확인하고, 이전 릴리즈를 살펴보고, 오래된 커밋 기록을 검토하는 등의 과정을 포함한다. 그런 다음 개발자에게 사용법/스타일 가이드를 따라 기존에 존재했던 클래스, 함수 등에 대한 API 기록을 문서화하도록 안내한다.

안타깝게도 이 과정을 효과적으로 자동화할 방법은 찾지 못했다. 이 작업은 아마도 AI/ML 엔지니어에게 적합한 과제일 것이다. 하지만 나는 그런 기술을 갖추지 못했고, API 기록에 잘못된 정보를 실수로 추가할까 봐 두려웠다. 설령 자동화를 하더라도 결국에는 사람이 정보를 검증해야 할 것이다 😕. 이 작업은 아마도 파일별로 수동으로 진행해야 할 것이다. Node.js 문서 작업에서도 그랬듯이.

주요 결과물​

  • api-history.schema.json

  • lint-markdown-api-history.ts

    • 커스텀 YAML(기술적으로 JSON) 스키마에 따라 작성된 API 기록을 검증하는 스크립트.
      • 유용한 오류 메시지
      • 상세한 문서/코드 주석
      • 광범위한 Vitest 테스트
      • 우수한 성능
    • 구현: electron/lint-roller#73
    • 사용: electron/electron#42982

  • preprocess-api-history.ts

    • 잘못된 API 기록이 저장소에 들어가는 경우를 대비해 간단한 검증을 수행한다. 또한 API 기록 블록을 감싸는 HTML 주석 태그를 제거한다. Docusaurus가 이를 파싱할 수 없기 때문이다.
    • 구현/사용: electron/website#594

  • transformers/api-history.ts

    • 마크다운 문서 파일에 있는 YAML API 기록 블록을 React 테이블(ApiHistoryTable.tsx)로 변환하는 스크립트.
    • 구현/사용: electron/website#594

  • ApiHistoryTable.tsx

    • 파싱된 API 기록 데이터를 문서 웹사이트에 표시하기 위한 React 테이블 컴포넌트.
      • 웹사이트 디자인과 일관된 스타일링
      • 반응형, 접근성, 그리고 일반적으로 잘 작성된 HTML, CSS, JS
    • 구현/사용: electron/website#594

  • styleguide.md

    • 새로운 API 기록 문서 시스템을 위한 사용/스타일 가이드 섹션.
      • 이해하기 쉬움
      • 잘 작성됨
      • 예제 포함
    • 구현/사용: electron/electron#42982

  • api-history-migration-guide.md

    • 새로운 API 기록 문서 시스템을 위한 마이그레이션 가이드.
      • 이해하기 쉬움
      • 잘 작성됨
      • 예제 포함
    • 구현/사용: electron/electron#42982

결론​

이번 기능을 구현하면서 많은 즐거움을 느꼈고, 코드 리뷰와 팀과의 다양한 구현 세부 사항 논의를 통해 귀중한 경험을 얻을 수 있었다.

문서에 API 기록을 추가함으로써, 특히 몇 년 전 버전의 Electron에서 기존 앱을 마이그레이션하려는 개발자들의 삶이 훨씬 더 쉬워질 것이라고 믿는다.

또한, 나의 멘토들에게 진심으로 감사드리고 싶다:

...그리고 나의 질문에 답변해주고, 풀 리퀘스트에 피드백을 주기 위해 시간을 내준 Electron 팀의 모든 멤버들에게도 감사드린다. 정말로 감사하다.