• CLI의 우선 순위
• UX 스타일 가이드 및 원칙
  • 생성기 사용 시기
  • 사용자가 기대하는 바
  • 개발 환경에 대한 기대 사항
  • 사용자와의 기대 조율
  • 사용자에게 정보 전달
  • 사용자로부터 정보 수집
• 디자인 팁
• 개발 관행
• FAQ

내부 이벤트 CLI에 기여하기

CLI의 우선 순위

1. CLI는 모든 계측 작업의 진입점으로 의도된 만큼 계측 기능과 기능 일치를 이루어야 합니다.

2. 성능 및 수동 테스트가 최우선 사항이며, CLI는 사용자가 깔끔하고 명확한 UX를 제공하는 원인이 됩니다.

3. 사용자가 CLI를 사용하지 않기로 선택하는 경우, danger/specs/pipelines는 여전히 정의 유효성/데이터 무결성/기능성 등을 보장합니다.

UX 스타일 가이드 및 원칙

생성기 사용 시기

내부 이벤트 생성기는 다음과 같아야 합니다:

• 메트릭 계측과 관련된 모든 엔지니어링 작업을 위한 원스톱 샵이어야 합니다.

내부 이벤트 생성기는 다음과 같아서는 안 됩니다:

• 필수는 아니며, 사용자는 동일한 작업을 수동으로 수행할 수 있어야 합니다.

사용자가 기대하는 바

내부 이벤트 생성기는 다음과 같아야 합니다:

• 사용자가 실수를 하지 않도록 보호해야 합니다.

• 사용자가 목표를 달성하기 위해 아직 완료해야 할 작업을 언제든지 의사소통해야 합니다.

• 화면에서 보이는 정보만을 기반으로 특정 옵션을 선택하거나 텍스트를 입력할 때의 결과를 의사소통해야 합니다.

내부 이벤트 생성기는 다음과 같아서는 안 됩니다:

• 사용자가 생성기를 실행하기 전에 계측에 대해 아는 것이 필요하지 않아야 합니다.

• 특정 작업을 완료하기 위해 필요한 컨텍스트가 필요한 경우 사용자가 화면을 전환해야 하지 않아야 합니다.

• 대체 경로를 제공하지 않고 사용자가 진행하지 못하도록 차단해서는 안 됩니다.

개발 환경에 대한 기대 사항

내부 이벤트 생성기는 다음과 같아야 합니다:

• 동일한 작업을 수동으로 수행하는 것보다 더 빨라야 합니다.

• 강제 종료 시 사용자 환경을 깔끔하고 유효한 상태로 유지해야 합니다.

내부 이벤트 생성기는 다음과 같아서는 안 됩니다:

• 잘못된 사용자 생성 콘텐츠가 있을 때 오류가 발생해서는 안 됩니다.

• Rails가 실행 중이어야 할 필요가 없습니다.

• 사용을 위해 기능하는 GDK가 필요하지 않아야 합니다.

사용자와의 기대 조율

내부 이벤트 생성기는 다음과 같아야 합니다:

• 각 화면 상단에 필요한 단계를 자세히 설명하는 진행률 표시줄을 보여야 합니다.

• 각 플로우를 정의하는 결과 기반 진입점이 있어야 합니다.

• 캐주얼하고 열정적인 톤을 사용해야 합니다.

사용자에게 정보 전달

내부 이벤트 생성기는 다음과 같아야 합니다:

• 모든 것에 대해 텍스트 레이블과 설명을 제공해야 합니다.

• 사용자가 CLI를 종료할 때 항상 InternalEventsCli::Text::FEEDBACK_NOTICE를 출력해야 합니다.

• 결과를 설명하기 위해 예시를 사용해야 합니다.

내부 이벤트 생성기는 다음과 같아서는 안 됩니다:

• 정보나 컨텍스트를 전달하기 위한 독점적인 메커니즘으로 색상 및 형식을 사용해서는 안 됩니다.

사용자로부터 정보 수집

내부 이벤트 생성기는 다음과 같아야 합니다:

• 일반 텍스트 입력보다 선택 메뉴를 선호해야 합니다.

• 가능한 경우 기본값을 자동으로 채우거나 이전 선택을 사용하여 정보를 추론해야 합니다.

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

• 항상 유효한 모든 옵션을 허용해야 하며, CLI는 가장 일반적인 사용 사례가 항상 사용된다고 가정해서는 안 됩니다.

내부 이벤트 생성기는 다음과 같아서는 안 됩니다:

• 사용자가 동일한 정보를 여러 번 다시 입력하도록 요구해서는 안 됩니다.

• CLI 전체 화면을 사용할 때 화면 “아래로 넘어가는” 상호작용이 확대되어서는 안 됩니다(가능한 경우).

디자인 팁

• 다양한 유형의 정보와 입력을 형식화하기 위해 scripts/internal_events/cli/helpers/formatting.rb를 참조하세요.

• 콘텐츠를 추가하거나 제거하면 흐름의 작동 방식이 변경될 수 있습니다. 항상 더 넓은 맥락을 고려하고 UX를 개선하기 위해 다른 수정을 두려워하지 마세요.

• 종속성과 검증이 있는 다중 선택 메뉴 대신 각 허용되는 조합을 나열하는 단일 선택 메뉴를 사용하는 것을 고려하세요. 이것은 항상 잘 작동하지 않을 수도 있지만, 더 빠른 상호작용을 제공하고 선택 결과를 사용자에게 더 명확하게 전달합니다.

• 기존 흐름에 추가할 때 기존 화면의 형식 및 구조를 최대한 가깝게 일치시켜야 합니다. 각 텍스트 조각의 역할에 대해 생각하고, a) 관련 텍스트를 기능별로 그룹화하거나, b) 관련 텍스트를 주제별로 그룹화하고 각 주제에 대해 동일한 기능적 순서를 사용하세요.

개발 관행

• 기능 문서화: 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는 정의에 대한 단일 진실 소스로서 json-schemas를 공유합니다.