머지 리퀘스트 위젯을 사용하면 디자인 프레임워크에 맞는 새 기능을 추가할 수 있습니다. 이 위젯을 사용하면 큰 노력 없이 다음과 같은 이점을 기본으로 얻습니다.

• 일관된 모양과 동작.
• 위젯이 열리는 시점 추적.
• 성능을 위한 가상 스크롤.

사용법#

위젯은 ~/vue_merge_request_widget/components/widget/widget.vue 컴포넌트를 사용하는 일반적인 Vue 컴포넌트입니다. 사용 사례의 복잡도에 따라 설정 객체를 전달하거나 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 computed 속성에 이름을 추가하면 위젯이 마운트됩니다.

<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 호출을 수행하는 함수를 전달합니다.

<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도 같은 방식으로 동작하지만, 사용자가 위젯을 펼칠 때만 호출됩니다.

데이터 구조#

Widget을 렌더링하는 데는 content와 summary 속성을 사용할 수 있습니다. 두 속성에 관한 설명은 다음과 같습니다.

// content
{
  text: '',           // Required: Main text for the row
  subtext: '',        // Optional: Smaller sub-text to be displayed below the main text
  supportingText: '', // Optional: Paragraph to be displayed below the subtext
  icon: {             // Optional: Icon object
    name: EXTENSION_ICONS.success, // Required: The icon name for the row
  },
  badge: {            // Optional: Badge displayed after text
    text: '',         // Required: Text to be displayed inside badge
    variant: '',      // Optional: GitLab UI badge variant, defaults to info
  },
  link: {             // Optional: Link to a URL displayed after text
    text: '',         // Required: Text of the link
    href: '',         // Optional: URL for the link
  },
  actions: [],        // Optional: Action button for row
  children: [],       // Optional: Child content to render, structure matches the same structure
  helpPopover: {      // Optional: If provided, an information icon will be display at the right-most corner of the content row
    options: {
      title: ''       // Required: The title of the popover
    },
    content: {
      text: '',           // Optional: Text content of the popover
      learnMorePath: '',  // Optional: The path to the documentation. A learn more link will be displayed if provided.
    }
  }
}

// summary
{
  title: '',    // Required: The main text of the summary part
  subtitle: '', // Optional: The subtext of the summary part
}

오류#

: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으로 표시하고 메트릭을 만들어야 보고할 수 있습니다.

위젯 하나에 대한 known 이벤트를 생성하는 절차는 다음과 같습니다.

1. 위젯 이름은 Widget${CamelName} 형식으로 정합니다.

   • 예를 들어 Test Reports 용 위젯은 WidgetTestReports가 됩니다.

2. ${CamelName}을 소문자 스네이크 케이스로 바꿔 위젯 이름 슬러그를 만듭니다.

   • 앞의 예시는 test_reports가 됩니다.

3. lib/gitlab/usage_data_counters/merge_request_widget_counter.rb의 WIDGETS 목록에 새 위젯 이름 슬러그를 추가합니다.

4. GDK가 실행 중인지 확인합니다(gdk start).

5. 다음 명령으로 커맨드 라인에서 known 이벤트를 생성합니다. 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. 새로 생성된 각 파일을 머지 리퀘스트 위젯 확장 텔레메트리의 기존 파일과 같은 형태로 수정합니다.

   • 기존 예시는 metrics/**/*_i_code_review_merge_request_widget_*처럼 glob 검색으로 찾습니다.
   • 대략적으로 각 파일에는 다음 값이 있어야 합니다.
     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. 다음 명령으로 커맨드 라인에서 known 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. 7단계 명령에 나열된 각 이벤트를(test_reports는 해당하는 이름 슬러그로 바꿔) 다음 집계 파일에 추가합니다.

   1. config/metrics/counts_7d/{timestamp}_code_review_category_monthly_active_users.yml
   2. config/metrics/counts_7d/{timestamp}_code_review_group_monthly_active_users.yml
   3. config/metrics/counts_28d/{timestamp}_code_review_category_monthly_active_users.yml
   4. config/metrics/counts_28d/{timestamp}_code_review_group_monthly_active_users.yml

새 이벤트 추가#

known 이벤트에 새 이벤트를 추가하는 경우 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 computed 속성으로 설정할 수 있습니다. 이 속성은 각 액션 버튼에 해당하는 객체의 배열을 반환해야 합니다.
• 레벨 2의 액션 버튼은 레벨 2 행 객체에 actions 키를 추가해 설정할 수 있습니다. 이 키의 값 역시 각 액션 버튼에 해당하는 객체의 배열이어야 합니다.

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

{
  text: 'Click me',
  href: this.someLinkHref,
  target: '_blank', // Optional
}

내부 액션 버튼은 다음 구조를 따릅니다.

{
  text: 'Click me',
  onClick() {}
}

데모#

모든 위젯이 함께 표시된 예시는 GitLab MR Widgets Demo에서 확인할 수 있습니다.