CLI의 우선순위#

• CLI는 모든 계측 작업의 진입점으로 설계되었으므로, 계측 기능과의 기능 동등성 유지

• CLI는 주로 사용자에게 깔끔하고 명확한 UX를 제공하는 역할을 하므로, 성능 및 수동 테스트가 최우선 과제

• 사용자가 CLI를 사용하지 않기로 선택한 경우에도, danger/specs/파이프라인을 통해 정의 유효성/데이터 무결성/기능 등을 보장

UX 스타일 가이드 및 원칙#

제너레이터를 사용해야 하는 경우#

Internal Events 제너레이터는 다음을 수행해야 합니다:

• 메트릭 계측과 관련된 모든 엔지니어링 작업을 위한 원스톱 쇼핑 창구 역할

Internal Events 제너레이터는 다음을 수행해서는 안 됩니다:

• 필수로 요구되어서는 안 됨; 사용자는 동일한 작업을 수동으로 수행할 수 있어야 함

사용자에 대한 기대치#

Internal Events 제너레이터는 다음을 수행해야 합니다:

• 사용자가 실수하지 않도록 보호

• 주어진 시점에 목표를 달성하기 위해 아직 완료해야 할 작업을 안내

• 화면에 표시된 정보만을 기반으로 특정 옵션 선택 또는 텍스트 입력의 결과를 안내

Internal Events 제너레이터는 다음을 수행해서는 안 됩니다:

• 제너레이터를 실행하기 전에 계측에 대해 미리 알아야 하도록 요구

• 특정 작업을 완료하기 위해 특정 컨텍스트가 필요한 경우 화면 전환을 요구

• 대안적인 경로를 제시하지 않고 사용자가 진행하지 못하도록 차단

개발 환경에 대한 기대치#

Internal Events 제너레이터는 다음을 수행해야 합니다:

• 동일한 작업을 수동으로 수행하는 것보다 빠르게 실행

• 강제 종료 시 사용자의 환경을 깔끔하고 유효한 상태로 유지

Internal Events 제너레이터는 다음을 수행해서는 안 됩니다:

• 잘못된 사용자 생성 콘텐츠가 존재할 때 중단

• Rails가 실행 중이어야 하는 조건을 요구

• 사용을 위해 작동하는 GDK를 요구

사용자와의 기대치 설정#

Internal Events 제너레이터는 다음을 수행해야 합니다:

• 각 화면 상단에 진행 표시줄과 필요한 단계를 표시

• 각 플로우를 정의하는 결과 기반 진입점 사용

• 친근하고 열정적인 톤 사용

사용자에게 정보 전달#

Internal Events 제너레이터는 다음을 수행해야 합니다:

• 모든 것에 대해 텍스트 레이블과 설명 제공

• 사용자가 CLI를 종료할 때 항상 InternalEventsCli::Text::FEEDBACK_NOTICE 출력

• 예시를 사용하여 결과를 설명

Internal Events 제너레이터는 다음을 수행해서는 안 됩니다:

• 색상 및 포맷을 정보나 컨텍스트를 전달하는 유일한 수단으로 사용

사용자로부터 정보 수집#

Internal Events 제너레이터는 다음을 수행해야 합니다:

• 일반 텍스트 입력보다 선택 메뉴를 선호

• 가능한 경우 기본값으로 자동 완성하거나 이전 선택을 사용하여 정보 유추

• 가장 일반적인 사용 사례를 첫 번째/가장 쉬운/기본 옵션으로 선택

• 항상 유효한 모든 옵션을 허용; CLI는 가장 일반적인 사용 사례가 항상 사용된다고 가정해서는 안 됨

Internal Events 제너레이터는 다음을 수행해서는 안 됩니다:

• 사용자가 동일한 정보를 여러 번 다시 입력하도록 요구

• CLI를 전체 화면으로 사용할 때 가능한 경우 화면의 "접힌 부분" 이상으로 확장되는 인터랙션 사용

디자인 팁#

• 다양한 유형의 정보와 입력 포맷에 대해서는 scripts/internal_events/cli/helpers/formatting.rb를 참고하세요.

• 콘텐츠를 추가하거나 제거하면 플로우가 얼마나 잘 작동하는지 바뀔 수 있습니다. 항상 더 넓은 컨텍스트를 고려하고, UX를 개선하기 위해 다른 수정을 적극적으로 수행하세요.

• 의존성 및 유효성 검사가 있는 다중 선택 메뉴 대신, 허용 가능한 각 조합을 나열하는 단일 선택 메뉴를 사용하는 것을 고려하세요. 항상 잘 작동하는 것은 아니지만, 더 빠른 인터랙션을 제공하고 선택 결과를 사용자에게 더 명확하게 만들어 줍니다.

• 기존 플로우에 추가할 때는 기존 화면의 포맷과 구조를 최대한 맞추세요. 각 텍스트 부분이 어떤 기능을 하는지 생각하고, a) 관련 텍스트를 기능별로 그룹화하거나, b) 관련 텍스트를 주제별로 그룹화하고 각 주제에 동일한 기능 순서를 사용하세요.

개발 관행#

• 기능 문서화: CLI 업데이트와 함께 문서 업데이트를 동시 릴리즈

CLI가 모든 계측을 위한 권장 진입점이라면, 항상 기능이 완전해야 합니다. 문서나 다른 팀에 공지된 기능보다 뒤처져서는 안 됩니다.

• CLI 문서화: 가능한 한 CLI 코드의 인라인 또는 함께 위치한 문서를 최대한 활용

CLI 작업을 하면서 컨텍스트/설명을 우연히 발견할 가능성이 높을수록, a) 사용되지 않는/중복된 코드의 가능성 감소 및 b) 코드 탐색성 향상과 재숙지 속도 향상으로 이어집니다.

• 테스트: 프론트엔드 애플리케이션과 동일한 방식으로 테스트 접근

자동화된 테스트는 주로 UX 지향적인 E2E 테스트여야 하며, 필요에 따라 엣지 케이스 테스트와 단위 테스트를 보완적으로 사용합니다.

• 회귀를 방지하기 위해 절대적으로 필요한 곳에 단위 테스트를 적용하세요.

• 검증: 기능 지원을 추가할 때 항상 CLI를 직접 실행

자동화된 테스트에만 의존하고 싶지 않습니다. 훌륭한 사용자 경험이 목표라면, 사용자로서 우리가 병합하는 모든 것이 그 목표를 달성하는지 확인하는 중요한 도구입니다. 수동 테스트가 번거롭고 귀찮다면, 사용하는 것도 아마 번거롭고 귀찮을 것입니다.

FAQ#

Q: InternalEventsCli::Event와 InternalEventsCli::Metric이 Gitlab::Tracking::EventDefinition 및 Gitlab::Usage::MetricDefinition을 사용하지 않는 이유는 무엇인가요?

A: EventDefinition 및 MetricDefinition 클래스를 사용하려면 GDK가 실행 중이고 Rails 앱이 로드된 상태여야 합니다. CLI의 성능은 사용성에 매우 중요하므로, 빠른 시작 시간이 제공하는 가치를 위해 별도의 클래스를 사용하는 것이 의미 있습니다. 이상적으로는, 언젠가 CLI와 Rails 앱 모두에 동일한 클래스를 사용할 수 있도록 리팩토링될 것입니다. 현재는 Rails 앱과 CLI가 정의를 위한 단일 진실 공급원(Single Source Of Truth, SSOT)으로 json-schemas를 공유합니다.