최근 회사에서 디자인 시스템의 색상 코드를 마이그레이션하는 작업을 진행했다.
기존 디자인 시스템에 정의된 색상 토큰을 새로운 디자인 가이드에 맞게 수정하고, 이를 참조하는 화면들도 함께 변경하는 작업이었다.
그런데 작업이 develop 브랜치에 병합된 이후, QA 과정에서 일부 화면에 의도하지 않은 색상이 적용된 문제가 발견되었다.
원인은 다른 팀원이 병렬로 개발하던 PR에 있었다.
tlqkf 이게 무슨일이야.
당시 프로젝트에서는 색상을 직접 Hex 값으로 사용하는 대신, 디자인 시스템에 정의된 색상 토큰을 참조하고 있었다.
뭐 예를 들어 아래처럼 정의해서 쓴다고 하겠다.
abstract final class AppColors {
static const orange100 = Color(0xFFFFF3E0);
static const orange200 = Color(0xFFFFCC80);
static const orange300 = Color(0xFFFFA726);
}마이그레이션 과정에서 기존 색상 토큰의 이름은 유지하면서 Hex 값을 변경했다.
// Before
static const orange200 = Color(0xFFFFCC80);
// After
static const orange200 = Color(0xFFFFB74D);위 코드는 상황을 설명하기 위한 예시다.
기존에 orange200을 참조하던 화면들은 변경된 색상 값을 사용하게 되므로, 마이그레이션 과정에서 영향을 받는 화면도 함께 수정했다.
헌데, 동일한 시점에 다른 팀원도 신규 화면을 개발하고 있었다.
해당 팀원은 마이그레이션 이전의 디자인 시스템을 기준으로 이전 색상 뭐 예를 들어 orange200을 사용하고 있었다.
Container(
color: AppColors.orange200,
)다른 팀원의 PR이 먼저 병합되고, 이후 디자인 시스템 마이그레이션 PR이 먼저 develop에 병합되었다.
그 결과 신규 화면에서 참조하는 orange200의 실제 Hex 값이 개발 당시와 달라졌다.
Git 충돌 X
두 PR의 변경 사항은 서로 다른 파일에 존재했다.
디자인 시스템 마이그레이션 PR에서는 색상 정의를 변경했다.
- static const orange200 = Color(0xFFFFCC80);
+ static const orange200 = Color(0xFFFFB74D);반면 다른 팀원의 PR에서는 기존 색상 토큰을 사용하는 코드를 추가했다.
+ Container(
+ color: AppColors.orange200,
+ )Git은 두 변경 사항을 충돌 없이 병합할 수 있었다.
하지만 orange200을 참조하는 코드가 기대하는 색상과 실제 색상은 달라진 상태였다.
최신 develop을 기준으로 리베이스하더라도 Git이 이러한 차이를 자동으로 감지할 수 있는 것은 아니다.
컴파일 오류도 발생하지 않았다.
결국 문제는 QA 과정에서 실제 화면을 확인하면서 발견되었다.
코드 리뷰에서 무엇을 놓쳤을까?
우리파트는 개발 과정에서는 PR을 통한 코드 리뷰가 이루어지고 있다.
하지만 리뷰에서 다른 PR에서 진행된 공통 리소스 변경의 영향까지 확인하지는 못했다.
문제가 발생한 코드를 보면 그 이유를 알 수 있다.
color: AppColors.orange200,디자인 시스템에서 제공하는 색상 토큰을 참조한 일반적인 코드다.
이 코드만으로는 잘못된 부분을 찾기 어렵다.
실제로 문제가 발생한 이유는 코드 작성 당시와 병합 이후의 orange200이 서로 다른 색상을 가리키고 있었기 때문이다.
결과적으로 각각의 PR을 검토했지만, 두 PR이 함께 병합되었을 때의 결과는 충분히 검증하지 못했다.
어떻게 방지할 수 있었을까?
이번 사례에서는 공통 리소스 변경에 따른 영향 범위를 어디까지 확인해야 하는지 생각해 보게 되었다.
우선 디자인 시스템처럼 여러 화면에서 사용하는 코드를 변경할 때는 현재 브랜치에서 참조하는 코드뿐만 아니라, 개발 중인 다른 PR에도 영향을 줄 수 있다는 점을 고려해야 한다.
특히 기존 토큰의 이름을 유지하면서 내부 값을 변경하는 경우에는 코드상으로 변경이 드러나지 않을 수 있다.
마치며
이번 문제는 컴파일 오류도, Git 충돌도 발생하지 않았다.
개발 과정에서 각각의 PR은 정상적인 코드처럼 보였지만, 병합 이후에는 의도하지 않은 색상이 적용되었다.
그리고 이를 개발 단계에서 발견하지 못하고 QA 과정에서 확인하게 되었다.
공통 코드를 변경할 때는 변경된 코드 자체뿐만 아니라 해당 코드를 참조하는 다른 작업까지 고려해야 한다.
특히 여러 작업이 동시에 진행되는 환경에서는 개별 PR에 대한 코드 리뷰만으로 모든 변경의 영향을 확인하기 어렵다.
앞으로 디자인 시스템처럼 영향 범위가 넓은 코드를 변경할 때는 진행 중인 PR과의 연관성을 확인하고, 가능한 범위에서 시각적 회귀 테스트를 통해 검증할 필요가 있겠다고 생각했다.