Airflow 오픈소스 기여 튜토리얼

실무에서 Airflow 를 계속 쓰다 보니 기여해 보고 싶었던 포인트가 쌓여갔다. 그런데 opensource 들은 고유의 생태계가 있기 때문에 contributing 이전에 서비스에 대한 애정을 담아 약간의 내용 숙지가 필요하다!

오늘은 Airflow Contribution 을 위한 한국어 튜토리얼 문서를 작성해 보고자 한다
(너무 간단해서 그런지 마땅한 문서가 없었다더라 ... 😇 본 문서는 입문자를 대상임을 강조해 본다)

✔️ 최근 v2 -> v3 으로 버전 업을 거치면서 기여할 포인트가 많기 생겼기 때문에 컨트리뷰터를 꿈꿨던 사람에겐 지금이 적기라고 권장하고 싶다

1️⃣ Brief Guideline

서두에 강조했던 Airflow Contribution 생태계에 대한 내용은 이미 repository 에 자세히 기술되어 있다
먼저 이 문서를 가볍게 정독해 보자

Link: https://github.com/apache/airflow/tree/main/contributing-docs

기여 순서나 개발 환경 세팅, 코드 컨벤션 등 필요한 내용이 다 들어있어서 한 번만 제대로 훑어봐도 감 잡는 것이 가능하다

참고로 apache-airflow.slack.com 공식 Slack Workspace 도 제공한다
이곳에서 커미터, 컨트리뷰터들의 논의 히스토리도 확인 가능하니 필요 시 참고할 것

2️⃣ Dev Env Setup

문서 숙지가 기여를 위한 첫걸음이라면 개발 환경 설정은 그 다음으로 중요한 부분 🖍

공식 문서의 내용이 워낙 폭넓기 때문에 본 튜토리얼에서는 개발 환경 설정 핵심만 콕 집어 안내하고자 한다

🧷 Airflow는 breeze 와 pre-commit 을 통해 통일된 개발 환경을 유지하고 있다

왜 Breeze를 쓰는가?

• pre-commit - 코드 스타일/린트/포맷 등 자동 검사
• breeze - 컨테이너를 통한 개발 환경 관리

breeze는 docker 기반으로 복잡한 의존성 문제를 한 번에 해결하고
실제 배포 환경과 유사한 테스트 환경을 바로 띄울 수 있다는 장점을 제공한다는 특징이 있다
-> 즉, os 나 python 버전 및 기타 의존성으로 인한 문제를 최소화할 수 있다는 이야기
-> 오픈소스 개발 환경에 적합하다고 볼 수 있다

🧷 기여 환경 세팅 가이드

$ brew install python@3.11

$ mkdir ~/workspace/airflow-dev
$ cd ~/workspace/airflow-dev

$ python3.11 -m venv venv
$ source venv/bin/activate
$ pip install --upgrade pip

# 예시: fork한 airflow 저장소로 이동
cd ~/workspace/airflow  # git clone한 디렉토리
# breeze 설치 (pipx, uv, 또는 pip 중 택1)
$ pip install apache-airflow
$ airflow db reset
$ airflow db migrate
$ pip install -e ./dev/breeze


# breeze로 Airflow 개발 환경 시작
$ breeze start-airflow
$ breeze start-airflow --dev-mode # 개발 모드

# breeze 오류 발생 시 docker 상태 확인
# * macos 의 경우 docker desktop이 설치 및 실행 중이어야 정상 동작함
$ docker --version
$ docker ps

🧷 Breeze 대시보드로 로컬 환경 관리

설정이 성공적으로 완료되면 아래와 같은 대시보드로 로컬 환경을 관리할 수 있다
문제 발생 시 대시보드에서 오류 로그 확인이 가능하기 때문에 효율적인 트러블슈팅이 가능하다

     cd airflow/ui
     pnpm install
     pnpm dev

# dag 폴더 확인이 안 돼?

/opt/airflow# airflow dags list
dag_id   | fileloc                 | owners  | is_paused | bundle_name | bundle_version
=========+=========================+=========+===========+=============+===============
test_dag | /files/dags/test_dag.py | airflow | False     | dags-folder | None

/opt/airflow# ls /opt/airflow/dags
test_dag_versioning.py

# /opt/airflow/dags: 일반적으로 로컬 dags/ 폴더 마운트 위치
# /files/dags: breeze 테스트나 샘플용 마운트 경로
$ breeze config show
* Backend: sqlite
* Postgres version: 13
* MySQL version: 8.0

* ASCIIART: enabled
* Cheatsheet: enabled

# 파일이 왜 안 잡히지? (dashboard 에서)
# 이걸로 경로 확인
$ airflow config get-value core dags_folder

# 종료 시
$ docker ps
$ docer ps {id}
$ breeze down --cleanup-build-cache
$ airflow db reset

$ AIRFLOW__CORE__DAGS_FOLDER=/opt/airflow/dags breeze start-airflow

🧷 성공적인 기여를 위한 마지막 포인트, Test Coverage

기능 수정이나 신규 feature 를 추가한 경우 pre-commit 을 통과하는 것도 중요하지만
pytest 로 구현된 unittest 도 적절히 수정하는 것이 아주 중요하다

기존 기능을 헤치면 안 되기 때문!

# 전체 검사를 수행하거나 단일 테스트 수행도 가능
# example)
$ pytest airflow-core/tests/unit/api_fastapi/core_api/routes/public/...

docker mount 를 통해서 아래와 같이 pytest debugging 도 가능하다

🧷 Merge 를 위한 마지막 관문

모든 관문을 거쳐 어렵게 push 한 내 PR 이 merge 되기 위해서는
설정된 Rule 을 통과해야 한다

Test Coverage 를 충족하는 것은 물론, 최소 인원의 리뷰어의 승인을 받아야 한다
복잡한 기능일 수록 이 과정에서 커미터 및 유관자들과의 논의가 길어질 수 있다

모든 Airflow 컨트리뷰터들의 건투를 빈다!

(* 오류 정정 및 논의는 언제나 감사합니다)