Skip to Content
ResourcesContributing Guide

Contributing Guide

Vortex UI 프로젝트 기여 가이드

개요

Vortex UI에 기여해주셔서 감사합니다! 이 가이드는 프로젝트에 기여하는 방법을 설명합니다.

Code of Conduct

우리의 약속

포용적이고 환대하는 환경을 만들기 위해 우리는 다음을 약속합니다:

  • ✅ 존중과 배려로 소통하기
  • ✅ 다양한 관점과 경험을 환영하기
  • ✅ 건설적인 피드백 주고받기
  • ✅ 커뮤니티의 최선의 이익을 우선하기

금지 행위

  • ❌ 괴롭힘, 차별, 혐오 발언
  • ❌ 개인정보 침해
  • ❌ 트롤링 및 악의적 댓글
  • ❌ 기타 비전문적 행위

Getting Started

1. 개발 환경 설정

# Repository 클론
git clone git@repo.calsplatz.com:vortex/platform.git
cd platform
 
# 의존성 설치
pnpm install
 
# 개발 서버 실행
pnpm dev

필수 요구사항:

  • Node.js 20+
  • pnpm 9+
  • Git

2. 프로젝트 구조 이해

platform/
├─ apps/
│   ├─ docs/          # Design System 문서
│   └─ storybook/     # Component 데모
├─ packages/
│   ├─ ui/            # Component 라이브러리
│   └─ cli/           # CLI 도구
└─ turbo.json         # Turborepo 설정

3. Branch Automation 사용

Interactive Mode (개발자):

# 브랜치 생성
pnpm branch
# → type, scope, description 선택
 
# 커밋
git add .
pnpm commit
# → subject만 입력
 
# Push 및 MR
pnpm push
pnpm mr

상세 가이드: Branch-Automation-Guide.md

Contribution Workflow

1. Issue 생성

새로운 기능이나 버그를 발견했다면:

  1. 기존 Issue 검색

    • 중복 방지를 위해 먼저 검색

  2. Issue Template 사용

    ## Description
 
명확한 설명
 
## Steps to Reproduce (버그인 경우)
 
1. ...
2. ...
 
## Expected Behavior
 
예상 동작
 
## Actual Behavior
 
실제 동작
 
## Screenshots
 
스크린샷 (선택)
 
## Environment
 
- OS: macOS 14
- Browser: Chrome 120
- Version: 2.0.0

  3. 라벨 추가

    • bug: 버그 수정
    • feature: 새로운 기능
    • documentation: 문서 개선
    • enhancement: 기존 기능 개선

2. Branch 생성

# Feature 브랜치
pnpm branch --type feature --scope ui --desc "add-tooltip-component" --yes
 
# Bug Fix 브랜치
pnpm branch --type fix --scope ui --desc "button-disabled-state" --yes
 
# Documentation 브랜치
pnpm branch --type docs --scope docs --desc "update-installation-guide" --yes

Branch Naming Convention:

  • feature/<scope>-<description>
  • fix/<scope>-<description>
  • docs/<scope>-<description>

3. 개발

Component 추가 (packages/ui)

cd packages/ui
 
# shadcn/ui로 컴포넌트 추가
pnpm dlx shadcn@latest add tooltip
 
# 수동 커스터마이징
# src/components/ui/tooltip.tsx 수정

체크리스트:

  • ✅ TypeScript 타입 정의
  • ✅ 접근성 준수 (ARIA, 키보드 네비게이션)
  • ✅ Responsive 디자인
  • ✅ Dark mode 지원
  • ✅ JSDoc 주석 작성

테스트 작성

// src/components/ui/__tests__/tooltip.test.tsx
import { describe, it, expect } from "vitest";
import { render, screen } from "@testing-library/react";
import { Tooltip } from "../tooltip";
 
describe("Tooltip", () => {
  it("renders trigger and content", () => {
    render(
      <Tooltip>
        <TooltipTrigger>Hover me</TooltipTrigger>
        <TooltipContent>Tooltip content</TooltipContent>
      </Tooltip>
    );
 
    expect(screen.getByText("Hover me")).toBeInTheDocument();
  });
 
  it("shows content on hover", async () => {
    // ...
  });
});

Storybook Story 작성

// apps/storybook/stories/Tooltip.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Tooltip, TooltipTrigger, TooltipContent } from "@vortex/ui";
 
const meta: Meta<typeof Tooltip> = {
  title: "Components/Tooltip",
  component: Tooltip,
  tags: ["autodocs"],
};
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Default: Story = {
  render: () => (
    <Tooltip>
      <TooltipTrigger>Hover me</TooltipTrigger>
      <TooltipContent>Tooltip content</TooltipContent>
    </Tooltip>
  ),
};

문서 작성

// apps/docs/app/components/tooltip/page.mdx
 
# Tooltip
 
간단한 정보를 표시하는 툴팁 컴포넌트
 
## 언제 사용하는가
 
- 버튼이나 아이콘에 부가 설명이 필요할 때
- 긴 텍스트를 생략하고 전체 내용을 보여줄 때
 
## 기본 사용법
 
\`\`\`tsx
 
<Tooltip>
  <TooltipTrigger>Hover me</TooltipTrigger>
  <TooltipContent>Tooltip content</TooltipContent>
</Tooltip>
\`\`\`

4. 커밋

Conventional Commits 사용:

git add .
pnpm commit --message "Add tooltip component with accessibility support" --yes
# 결과: feat(ui): Add tooltip component with accessibility support

Commit Message 구조:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: 새로운 기능
  • fix: 버그 수정
  • docs: 문서 변경
  • style: 코드 스타일 (formatting)
  • refactor: 리팩토링
  • test: 테스트 추가/수정
  • chore: 빌드, 설정 변경

5. Push 및 MR

# Push
pnpm push --yes
 
# MR 생성
pnpm mr --target develop --yes

MR Description Template:

## What
 
이 MR이 하는 일
 
## Why
 
왜 필요한지
 
## How
 
어떻게 구현했는지
 
## Testing
 
테스트 방법
 
## Screenshots
 
스크린샷 (UI 변경사항인 경우)
 
## Checklist
 
- [ ] 테스트 작성 및 통과
- [ ] Storybook Story 추가
- [ ] 문서 업데이트
- [ ] CHANGELOG.md 업데이트
- [ ] 타입 체크 통과
- [ ] Lint 통과

6. Code Review

Review 과정:

  1. 자동 검사 통과

    • CI/CD 파이프라인
    • Type check
    • Lint
    • Tests

  2. Reviewer 지정

    • CODEOWNERS에 의한 자동 할당
    • 또는 수동 지정

  3. 피드백 반영

    # 피드백 반영 후 커밋
git add .
pnpm commit --message "Address review feedback" --yes
pnpm push --yes

  4. 승인 및 Merge

    git checkout develop
pnpm merge --mr <MR-NUMBER> --delete-branch --yes

Component Development Guidelines

1. 접근성 (Accessibility)

필수 요구사항:

  • ✅ WCAG 2.1 AA 준수
  • ✅ 적절한 ARIA 속성
  • ✅ 키보드 네비게이션
  • ✅ 스크린 리더 지원
  • ✅ 색상 대비 충족

예시:

<button
  aria-label="Close dialog"
  aria-pressed={isPressed}
  onClick={handleClick}
  onKeyDown={handleKeyDown}
>
  Close
</button>

2. 타입 안전성

import * as React from "react";
import { VariantProps } from "class-variance-authority";
 
interface TooltipProps
  extends React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Root> {
  children: React.ReactNode;
}
 
const Tooltip = React.forwardRef<
  React.ElementRef<typeof TooltipPrimitive.Root>,
  TooltipProps
>(({ children, ...props }, ref) => {
  return (
    <TooltipPrimitive.Root ref={ref} {...props}>
      {children}
    </TooltipPrimitive.Root>
  );
});
 
Tooltip.displayName = "Tooltip";
 
export { Tooltip };
export type { TooltipProps };

3. 스타일링

Tailwind CSS 사용:

<div className="rounded-md bg-popover px-3 py-1.5 text-sm text-popover-foreground shadow-md">
  {content}
</div>

CVA (class-variance-authority) 사용:

import { cva } from "class-variance-authority";
 
const tooltipVariants = cva("rounded-md px-3 py-1.5 text-sm shadow-md", {
  variants: {
    variant: {
      default: "bg-popover text-popover-foreground",
      destructive: "bg-destructive text-destructive-foreground",
    },
    size: {
      sm: "px-2 py-1 text-xs",
      md: "px-3 py-1.5 text-sm",
      lg: "px-4 py-2 text-base",
    },
  },
  defaultVariants: {
    variant: "default",
    size: "md",
  },
});

4. 성능 최적화

import { memo, useCallback, useMemo } from "react";
 
const TooltipContent = memo(({ children, ...props }) => {
  const content = useMemo(() => {
    // 복잡한 계산
    return processContent(children);
  }, [children]);
 
  const handleClick = useCallback(() => {
    // 이벤트 핸들러
  }, []);
 
  return <div onClick={handleClick}>{content}</div>;
});

Testing Guidelines

단위 테스트 (Vitest)

describe("Component", () => {
  it("renders correctly", () => {
    render(<Component />);
    expect(screen.getByText("...")).toBeInTheDocument();
  });
 
  it("handles user interaction", async () => {
    const user = userEvent.setup();
    render(<Component />);
 
    await user.click(screen.getByRole("button"));
    expect(mockFunction).toHaveBeenCalled();
  });
 
  it("supports keyboard navigation", async () => {
    const user = userEvent.setup();
    render(<Component />);
 
    await user.keyboard("{Enter}");
    expect(mockFunction).toHaveBeenCalled();
  });
});

접근성 테스트

import { axe } from "jest-axe";
 
it("has no accessibility violations", async () => {
  const { container } = render(<Component />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Documentation Guidelines

컴포넌트 문서 구조

# Component Name
 
간단한 설명
 
---
 
## 개요
 
상세 설명
 
### 주요 특징
 
- ✅ 특징 1
- ✅ 특징 2
 
---
 
## 설치
 
\`\`\`bash
npx @vortex/cli add component-name
\`\`\`
 
---
 
## 기본 사용법
 
\`\`\`tsx
import { Component } from "@/components/ui/component"
 
<Component>Content</Component>
\`\`\`
 
---
 
## Props
 
| Prop    | Type   | Default   | Description |
| ------- | ------ | --------- | ----------- |
| variant | string | "default" | 스타일 변형 |
 
---
 
## 예제
 
### 예제 1
 
\`\`\`tsx
 
<Component variant="primary">Example</Component>
\`\`\`
 
---
 
## 접근성
 
- 키보드 네비게이션 지원
- 스크린 리더 호환성
- ARIA 속성
 
---
 
## 다음 단계
 
관련 컴포넌트 링크

Release Process

1. Version 업데이트

# package.json version 업데이트
cd packages/ui
npm version patch  # 버그 수정
npm version minor  # 새로운 기능
npm version major  # Breaking changes

2. CHANGELOG 업데이트

## [2.1.0] - 2025-01-20
 
### Added
 
- Tooltip component with accessibility support
 
### Changed
 
- Improved Button loading state
 
### Fixed
 
- Select dropdown positioning issue

3. Git Tag

git tag -a v2.1.0 -m "Release v2.1.0"
git push origin v2.1.0

4. 배포

GitLab CI/CD가 자동으로:

  • Verdaccio에 npm 패키지 배포
  • Storybook 업데이트
  • Docs 사이트 업데이트

도움이 필요한가요?

커뮤니티

  • GitLab Issues: 버그 리포트, 기능 요청
  • Discussions: 질문, 아이디어 공유
  • Slack: 실시간 커뮤니케이션 (내부 팀)

Resources

다음 단계

Changelog

변경 이력

FAQ

자주 묻는 질문

Last updated on
@vortex/ui-icignal ChangelogCustomization