고급 검색 마이그레이션 리뷰 가이드라인

요약

이 페이지는 고급 검색 마이그레이션 리뷰에 특화되어 있습니다. 다음에 대해 고급 검색 마이그레이션 리뷰가 필요합니다: 작성자는 리뷰를 요청하기 전에 필수 아티팩트를 제공해야 합니다. 리뷰를 요청할 때 다음을 제공해야 합니다.

이 페이지는 고급 검색 마이그레이션 리뷰에 특화되어 있습니다. 일반적인 코드 리뷰에 대한 광범위한 조언과 모범 사례는 코드 리뷰 가이드를 참조하십시오.

리뷰가 필요한 경우#

다음에 대해 고급 검색 마이그레이션 리뷰가 필요합니다:

ee/elastic/migrate/의 파일 변경
인덱스 매핑 또는 설정 변경
Search::Elastic::References:: 또는 레거시 Elastic::Latest::InstanceProxy 클래스의 문서 직렬화 변경
인덱싱 동작이나 데이터 일관성에 영향을 미치는 변경

역할#

작성자는 리뷰를 요청하기 전에 필수 아티팩트를 제공해야 합니다. 리뷰어는 아티팩트가 완전한지 확인하고 1차 리뷰를 수행합니다. 관리자는 최종 리뷰를 수행하고 승인되면 병합합니다.

필수 아티팩트#

리뷰를 요청할 때 다음을 제공해야 합니다. 머지 요청 설명에 이러한 항목이 포함되지 않은 경우 리뷰가 작성자에게 다시 할당됩니다.

모든 마이그레이션#

마이그레이션 목적: 마이그레이션이 무엇을 하는지, 왜 필요한지.
영향을 받는 문서 유형: 어떤 인덱스와 문서 유형이 수정되는지(예: WorkItem, MergeRequest, Commit).
하위 호환성: 마이그레이션이 다중 버전 호환성을 처리하는 방법.
테스트: 로컬에서 마이그레이션을 실행하고 실행 후 completed?가 true를 반환하는지 확인. 배치 마이그레이션의 경우 배치 처리가 예상대로 작동하는지 확인.

매핑 또는 설정 변경#

전후 비교: 인덱스 구성에 대한 정확한 변경사항 표시.
영향 분석: 변경이 기존 문서, 검색 동작 및 성능에 미치는 영향.

백필 또는 재인덱스 마이그레이션#

데이터 볼륨 추정: 영향을 받는 문서의 대략적인 수.
런타임 추정: 계산 공식을 사용하여 GitLab.com에서 예상 실행 시간.
배치 크기 근거: 선택한 배치 크기와 제한 지연이 적절한 이유.
쿼리 계획(해당하는 경우): 실행 중인 Elasticsearch 쿼리.

데이터 수정 마이그레이션#

가역성: 마이그레이션이 되돌릴 수 있음을 확인하거나 왜 불가능한지 설명.
데이터 안전성: 데이터 손실 또는 손상에 대한 보호 조치.
유효성 검사: 마이그레이션이 성공적으로 완료되었는지 확인하는 방법.

리뷰 체크리스트#

기본 사항#

마이그레이션이 스타일 가이드 형식을 따릅니다.
머지 요청에 변경 로그가 있습니다.
적절한 마이그레이션 헬퍼가 사용됩니다.
공유 예시를 사용하는 적절한 테스트 커버리지가 있는 사양 파일이 존재합니다.
ee/elastic/docs/에 다음 필수 필드가 있는 YAML 문서 파일이 존재합니다:
- description - 마이그레이션이 하는 일
- introduced_by_url - 마이그레이션을 도입한 머지 요청 링크
- 건너뛸 수 있는 마이그레이션의 경우: skippable: true 및 skip_condition
- 더 이상 사용되지 않는 마이그레이션의 경우: marked_obsolete_by_url 및 marked_obsolete_in_milestone

하위 호환성#

마이그레이션 전 애플리케이션 코드가 여전히 실행 중인 경우를 처리합니다. 다중 버전 호환성을 참조하십시오.
파괴적인 작업(삭제, 필드 제거)은 필요한 경우 이후 릴리스로 연기됩니다.
문서 변경에 대해 schema_version이 적절하게 증가합니다. 형식은 YYVV(두 자리 연도 및 해당 연도 내 롤링 버전 카운터, 예: 24_46)입니다.
마이그레이션에 의존하는 코드는 새 필드나 동작을 사용하기 전에 Elastic::DataMigrationService.migration_has_finished?를 사용하여 마이그레이션이 완료되었는지 확인합니다.

데이터 안전성#

마이그레이션이 고아 상태이거나 일관성 없는 데이터를 도입하지 않습니다.
문서 수정의 경우: as_indexed_json 메서드가 일치하도록 업데이트됩니다.
인증 필드(visibility_level, traversal_ids 등)가 올바르게 처리됩니다.
마이그레이션이 Elastic::ProcessBookkeepingService의 지속적인 인덱싱과 충돌하지 않습니다.
사용자 지정 Elasticsearch 쿼리의 정확성이 검토됩니다.

성능#

계산 공식을 사용한 런타임 추정이 합리적입니다.
배치 크기가 10_000 문서를 초과하지 않습니다.
제한 지연이 배치 크기와 작업 복잡성에 적합합니다.
대용량 마이그레이션은 적절한 지연으로 batched!를 사용합니다.
마이그레이션의 경우: preload_indexing_data 메서드가 인덱싱 전에 관련 데이터를 효율적으로 로드합니다.
검색 결과의 경우: 모델에는 결과를 반환할 때 연관을 미리 로드하는 preload_search_data 범위가 포함됩니다.

인덱스 매핑#

매핑 변경은 Search::Elastic::Types:: 또는 레거시 Elastic::Latest::Config에 적용됩니다.
새 필드에는 적절한 유형 및 분석기가 있습니다.
필요한 경우 후속 백필 마이그레이션이 포함됩니다.

고급 검색 마이그레이션 리뷰어 신청 방법#

신청하려면 다음에 익숙해야 합니다:

또한 고급 검색 마이그레이션을 작성하거나 리뷰한 경험이 있어야 합니다.

팀원들은 다음을 통해 고급 검색 마이그레이션 도메인 전문가로 자신을 표명하도록 권장됩니다:

gitlab-advanced-search-migration 프로젝트 관리자 프로세스를 따라 머지 요청을 생성하십시오.
YAML 파일에 고급 검색 마이그레이션 전문성을 추가하십시오:
```
projects:
  gitlab:
    - reviewer advanced_search_migrations
```
머지 요청을 고급 검색 마이그레이션 관리자 또는 Global Search 엔지니어링 매니저에게 할당하십시오.

team.yml 업데이트가 병합된 후, 리뷰어 룰렛이 귀하를 고급 검색 마이그레이션 리뷰어로 추천할 수 있습니다.