병합 요청 위젯

병합 요청 위젯을 사용하면 디자인 프레임워크와 일치하는 새로운 기능을 추가할 수 있습니다. 이 위젯들을 사용하면 아래와 같은 많은 이점을 적은 노력으로 얻을 수 있습니다.

  • 일관된 느낌과 모양.
  • 위젯이 열릴 때 추적.
  • 성능을 위한 가상 스크롤링.

사용법

위젯들은 단순한 Vue 컴포넌트로, ~/vue_merge_request_widget/components/widget/widget.vue 컴포넌트를 사용합니다. 사용 사례의 복잡성에 따라 구성 객체를 전달하거나 slot을 통해 컴포넌트를 확장할 수 있습니다.

slot을 사용하는 예제는 다음 파일을 참조하세요. ee/app/assets/javascripts/vue_merge_request_widget/widgets/security_reports/mr_widget_security_reports.vue

데이터 객체를 사용하는 예제는 다음 파일을 참조하세요. ee/app/assets/javascripts/vue_merge_request_widget/widgets/metrics/index.vue

다음은 Hello World 위젯을 렌더링하는 최소한의 예제입니다: 

<script>
import MrWidget from '~/vue_merge_request_widget/components/widget/widget.vue';
import { __ } from '~/locale';

export default {
  name: 'WidgetHelloWorld',
  components: {
    MrWidget,
  },
  computed: {
    summary() {
      return { title: __('Hello World') };
    },
  },
};
</script>
<template>
  <mr-widget :summary="summary" :is-collapsible="false" :widget-name="$options.name" />
</template>

위젯 등록

위의 예제는 페이지에 어디에서도 렌더링되지 않습니다. 병합 요청 위젯 섹션에 마운트하려면 이 두 위치 중 하나 이상에서 위젯을 등록해야 합니다.

  • app/assets/javascripts/vue_merge_request_widget/components/widget/app.vue (CE 위젯의 경우)
  • ee/app/assets/javascripts/vue_merge_request_widget/components/widget/app.vue (CE 및 EE 위젯의 경우)

구성 요소를 구성 요소 목록에 정의하고 widgets 계산된 속성에 이름을 추가하면 위젯이 마운트됩니다. 

<script>
export default {
  components: {
    MrHelloWorldWidget: () =>
      import('ee/vue_merge_request_widget/widgets/hello_world/index.vue'),
  },
  computed: {
    mrHelloWorldWidget() {
      return this.mr.shouldRenderHelloWorldWidget ? 'MrHelloWorldWidget' : undefined;
    },
    widgets() {
      return [
        this.mrHelloWorldWidget,
      ].filter((w) => w);
    },
  },
};
</script>

데이터 가져오기

위젯이 마운트될 때 데이터를 가져오려면 :fetch-collapsed-data 속성에 API 호출을 수행하는 함수를 전달하면 됩니다.

경고: 함수는 response 객체로 해결되는 Promise를 반환해야 합니다. 구현은 계속해서 폴링하려면 POLL-INTERVAL 헤더에 의존하므로 상태 코드와 헤더를 변경하지 않는 것이 중요합니다. 

<script>
export default {
  // ...
  data() {
    return {
      collapsedData: [],
    };
  },
  methods: {
    fetchCollapsedData() {
      return axios.get('/my/path').then((response) => {
        this.collapsedData = response.data;
        return response;
      });
    },
  },
};
</script>
<template>
  <mr-widget :fetch-collapsed-data="fetchCollapsedData" />
</template>

:fetch-expanded-data도 동일한 방식으로 작동하지만 사용자가 위젯을 확장할 때에만 호출됩니다.

데이터 구조

content 및 summary 속성은 Widget을 렌더링하는 데 사용할 수 있습니다. 아래는 두 속성에 대한 설명서입니다. 

// content
{
  text: '',           // 필수: 행의 주요 텍스트
  subtext: '',        // 선택 사항: 주요 텍스트 아래에 표시할 작은 서브 텍스트
  supportingText: '', // 선택 사항: 서브 텍스트 아래에 표시할 단락
  icon: {             // 선택 사항: 아이콘 객체
    name: EXTENSION_ICONS.success, // 필수: 행의 아이콘 이름
  },
  badge: {            // 선택 사항: 텍스트 뒤에 표시되는 배지
    text: '',         // 필수: 배지 내에 표시할 텍스트
    variant: '',      // 선택 사항: 기본값은 info로 하는 GitLab UI 배지 변형
  },
  link: {             // 선택 사항: 텍스트 뒤에 표시되는 URL로 이동하는 링크
    text: '',         // 필수: 링크의 텍스트
    href: '',         // 선택 사항: 링크의 URL
  },
  actions: [],        // 선택 사항: 행에 대한 작업 버튼
  children: [],       // 선택 사항: 렌더링할 하위 콘텐츠, 구조가 동일해야 합니다.
  helpPopover: {      // 선택 사항: 제공되는 경우, 콘텐츠 행의 가장 오른쪽 모서리에 정보 아이콘이 표시됩니다.
    options: {
      title: ''       // 필수: 팝오버의 제목
    },
    content: {
      text: '',           // 선택 사항: 팝오버의 텍스트 내용
      learnMorePath: '',  // 선택 사항: 문서의 경로. 제공된 경우 더 알아보기 링크가 표시됩니다.
    }
  }
}

// summary
{
  title: '',    // 필수: 요약 부분의 주요 텍스트
  subtitle: '', // 선택 사항: 요약 부분의 하위 텍스트
}

오류

:fetch-collapsed-data 또는 :fetch-expanded-data 메서드에서 오류가 발생하는 경우에 대비하여 ‘error-text’ 속성을 사용하여 오류 텍스트를 사용자 정의할 수 있습니다. 

<template>
  <mr-widget :error-text="__('Failed to load.')" />
</template>

텔레메트리

위젯 프레임워크의 기본 구현에는 일부 텔레메트리 이벤트가 포함되어 있습니다. 각 위젯은 다음을 보고합니다.

  • view: 화면에 렌더링될 때.
  • expand: 확장될 때.
  • full_report_clicked: (선택 사항) 전체 보고서를 보려고 클릭했을 때.
  • 결과 (expand_success, expand_warning, 또는 expand_failed): 확장될 때 위젯의 상태와 관련된 세 가지 이벤트 중 하나.

새로운 위젯 추가

새 위젯을 추가할 때는 위에 언급된 이벤트를 known로 표시하고 보고 가능하게 만들기 위해 메트릭을 생성해야 합니다.

참고: EE 전용 이벤트인 경우, 아래 셸 명령의 끝에 --ee를 추가해야 합니다.

개별 위젯에 대해 아래 명령을 사용하여 이러한 알려진 이벤트를 생성하십시오.

  1. 위젯은 Widget${CamelName}으로 명명되어야 합니다.
    • 예: Test Reports 위젯의 경우 WidgetTestReports여야 합니다.
  2. ${CamelName}을 lower-, snake-case로 변환하여 위젯 이름 슬러그를 계산합니다.
    • 이전 예제의 경우 test_reports가 될 것입니다.
  3. lib/gitlab/usage_data_counters/merge_request_widget_counter.rb에서 새 위젯 이름 슬러그를 WIDGETS 목록에 추가합니다.
  4. GDK가 실행 중인지 확인하십시오 (gdk start).

  5. 다음 명령으로 명령줄에서 알려진 이벤트를 생성합니다. 적절한 이름 슬러그로 test_reports를 대체하십시오. 

    bundle exec rails generate gitlab:usage_metric_definition \
counts.i_code_review_merge_request_widget_test_reports_count_view \
counts.i_code_review_merge_request_widget_test_reports_count_full_report_clicked \
counts.i_code_review_merge_request_widget_test_reports_count_expand \
counts.i_code_review_merge_request_widget_test_reports_count_expand_success \
counts.i_code_review_merge_request_widget_test_reports_count_expand_warning \
counts.i_code_review_merge_request_widget_test_reports_count_expand_failed \
--dir=all
  6. 각 새로 생성된 파일을 기존의 병합 요청 위젯 확장 텔레메트리 파일과 일치하도록 수정합니다.
    • 기존 위젯 확장 텔레메트리 파일을 검토하여 존재하는 예제를 찾을 수 있습니다.
    • 대략적으로 말하자면, 각 파일은 다음과 같은 값을 가져야 합니다.
      1. description = 이 값에 대한 일반적인 영어 설명. 기존 위젯 확장 텔레메트리 파일을 검토하여 예제를 확인하십시오.
      2. product_section = dev
      3. product_stage = create
      4. product_group = code_review
      5. introduced_by_url = '[your MR]'
      6. options.events = (위의 명령에서 이 파일을 생성한 이벤트, 예를 들어 i_code_review_merge_request_widget_test_reports_count_view)
        • 이 값은 텔레메트리 이벤트가 ‘메트릭’에 연결되는 방식이므로 이 값은 아마도 가장 중요한 값 중 하나일 것입니다.
      7. data_source = redis
      8. data_category = optional

  7. 다음 명령으로 각 새로 생성된 파일을 사용하여 알려진 HLL 이벤트를 생성합니다. test_reports를 적절한 이름 슬러그로 대체하십시오. 

    bundle exec rails generate gitlab:usage_metric_definition:redis_hll code_review \
i_code_review_merge_request_widget_test_reports_view \
i_code_review_merge_request_widget_test_reports_full_report_clicked \
i_code_review_merge_request_widget_test_reports_expand \
i_code_review_merge_request_widget_test_reports_expand_success \
i_code_review_merge_request_widget_test_reports_expand_warning \
i_code_review_merge_request_widget_test_reports_expand_failed \
--class_name=RedisHLLMetric

  8. 단계 6을 반복하되, data_source를 redis_hll로 변경하십시오.

  9. config/metrics/counts_7d/{timestamp}_code_review_category_monthly_active_users.yml
    1. config/metrics/counts_7d/{timestamp}_code_review_group_monthly_active_users.yml
    2. config/metrics/counts_28d/{timestamp}_code_review_category_monthly_active_users.yml
    3. config/metrics/counts_28d/{timestamp}_code_review_group_monthly_active_users.yml에 각 이벤트를 추가하십시오.

새 이벤트 추가

기존 이벤트에 새 이벤트를 추가하는 경우 lib/gitlab/usage_data_counters/merge_request_widget_extension_counter.rb 파일의 KNOWN_EVENTS 목록에 새 이벤트를 포함하세요.

아이콘

레벨 1 및 이후 모든 레벨에는 고유의 상태 아이콘이 있을 수 있습니다. 디자인 프레임워크를 유지하기 위해 constants.js 파일에서 EXTENSION_ICONS 상수를 가져와야 합니다. 

import { EXTENSION_ICONS } from '~/vue_merge_request_widget/constants.js';

이 상수에는 아래와 같은 아이콘들이 사용 가능합니다. 디자인 프레임워크에 따라 레벨 1에서는 일부 아이콘만 사용해야 합니다:

  • failed
  • warning
  • success
  • neutral
  • error
  • notice
  • severityCritical
  • severityHigh
  • severityMedium
  • severityLow
  • severityInfo
  • severityUnknown

동작 버튼

각 확장 프로그램의 레벨 1 및 2에 동작 버튼을 추가할 수 있습니다. 이러한 버튼은 각 행에 대한 링크 또는 동작을 제공하는 방법으로 사용됩니다:

  • 레벨 1의 동작 버튼은 tertiaryButtons 계산된 속성을 통해 설정할 수 있습니다. 이 속성은 각 동작 버튼에 대한 객체 배열을 반환해야 합니다.
  • 레벨 2의 동작 버튼은 레벨 2 행 객체에 actions 키를 추가하여 설정할 수 있습니다. 이 키의 값 또한 각 동작 버튼에 대한 객체 배열이어야 합니다.

링크는 다음 구조를 따라야 합니다: 

{
  text: '여기를 클릭',
  href: this.someLinkHref,
  target: '_blank', // 선택 사항
}

내부 동작 버튼의 경우, 다음 구조를 따르세요: 

{
  text: '여기를 클릭',
  onClick() {}
}

데모

모든 위젯이 함께 표시된 예제를 보려면 GitLab MR 위젯 데모를 방문하세요.