YAML 주석 보존의 기술적 난제와 배경
YAML 사양에서 주석은 데이터 구조에 영향을 주지 않는 요소로 정의되므로, 대다수의 파서는 효율성을 위해 이를 무시합니다. Ruby의 기본 라이브러리인 Psych는 C로 작성된 libyaml을 기반으로 하며, 파일을 로드하고 수정 후 다시 덤프(dump)하는 과정에서 원본 주석과 들여쓰기 형식을 보존하지 못합니다. Discourse의 인프라 팀은 이를 해결하기 위해 다음과 같은 대안을 검토했으나 모두 한계가 있었습니다.
- 정규 표현식 사용: 단순한 치환은 가능하나 복잡한 YAML 구조에서는 쉽게 깨집니다.
- Psych AST 조작: 내부 추상 구문 트리(AST)를 직접 다루는 방식은 문서화되지 않았고 매우 불안정합니다.
- 타 언어 라이브러리 이식: Python의 ruamel.yaml 등을 포팅하는 것은 너무 방대한 작업이었습니다.
psych-pure의 도입과 후원을 통한 안정화
2021년 Discourse는 순수 Ruby로 작성된 psych-pure 라이브러리를 검토했으나, 당시에는 엣지 케이스 처리가 미흡하여 실제 운영 환경에 도입하기에는 무리가 있었습니다. 그러나 2025년 말, 개발자 Kevin Newton이 해당 프로젝트를 활발히 개선하고 있다는 소식을 접하고 Discourse는 공식적인 후원을 결정했습니다.
psych-pure의 핵심 설계 철학은 주석을 데이터와 별개의 요소가 아닌, 인접한 AST 노드에 부착된 속성으로 취급하는 것입니다. 이를 통해 데이터를 수정하고 다시 직렬화할 때 해당 노드에 붙어 있는 주석을 원래 위치에 다시 작성할 수 있게 되었습니다. Discourse는 후원을 통해 라이브러리의 안정성을 확보하고, 실제 운영 환경의 1,736개 YAML 파일을 대상으로 파싱 테스트를 수행하여 실패율 0%를 달성했습니다.
실무 적용 및 도구화
성공적인 검증 후 Discourse는 YamlHelper라는 내부 API를 구축하여 런북에 적용했습니다. 이를 통해 다음과 같은 실질적인 이점을 얻었습니다.
- 데이터 무결성 및 지식 보존: 데이터베이스 페일오버나 S3 키 교체와 같은 자동화 작업 중에도 “레거시 앱 호환을 위해 포트 변경 금지”와 같은 중요한 주석이 그대로 유지됩니다.
- 자동화 친화적 환경: 스크립트가 주석을 삭제하지 않는다는 신뢰가 생기면서 엔지니어들이 더 적극적으로 설정 파일에 맥락을 기록하게 되었습니다.
- yaml-janitor 개발: 주석을 보존하면서도 YAML 파일의 포맷 불일치를 자동으로 수정할 수 있는 린터(Linter) 도구를 추가로 개발하여 코드 품질을 높였습니다.
이러한 노력의 결과물인 psych-pure는 현재 RubyGems를 통해 누구나 사용할 수 있도록 공개되어 있으며, 이는 특정 기업의 문제를 해결하는 과정이 오픈 소스 생태계의 공통 도구를 개선하는 선순환 구조를 보여줍니다.