오픈소스 기여를 해보고 싶지만 어디서부터 시작해야 할지 모르겠다면, 이 글이 도움이 될 것입니다. Gitea 프로젝트에 템플릿 파일 5줄을 수정하는 작은 기여를 했고, 이슈 탐색부터 PR 머지까지의 전체 과정을 공유합니다.
Table of Contents
왜 Gitea였나
Gitea는 Go로 작성된 셀프 호스팅 Git 서비스입니다. GitHub와 비슷한 기능을 제공하는 오픈소스 프로젝트로, GitHub 스타 53k 이상의 활발한 커뮤니티를 가지고 있습니다.
Gitea에 관심을 가지게 된 계기는 회사 업무였습니다. 현재 직장에서 형상관리 시스템을 직접 구축하는 업무를 맡았는데, 여러 후보 중 Gitea를 선택하게 되었습니다. 도입을 위해 문서와 코드를 살펴보다 보니 자연스럽게 프로젝트에 대한 이해도가 높아졌고, 직접 기여도 해보고 싶다는 생각이 들었습니다.
실제로 기여를 시작하기 좋은 환경이기도 했습니다. good first issue 라벨이 잘 관리되어 있고, 라벨만 달아두고 방치하는 프로젝트가 많은데 Gitea는 메인테이너가 실제로 확인한 이슈에만 이 라벨을 달아둡니다.
기여할 이슈 찾기
검색 필터
GitHub에서 다음 필터로 이슈를 검색했습니다:
is:issue is:open label:"good first issue" -label:blocked -label:wait-for-triageCode language: plaintext (plaintext)good first issue만 필터링하면 안 됩니다. blocked나 wait-for-triage 라벨이 달린 이슈는 아직 작업할 수 없는 상태이기 때문에 제외해야 합니다.
이슈 선택 기준
검색 결과 4개의 이슈가 나왔습니다. 하나씩 분석했습니다.
| 이슈 | 제목 | 판단 |
|---|---|---|
| #36211 | Mirror 프로세스 중지 시 시스템 메시지에서 레포 이름 누락 | 탈락 - 이미 PR #36266이 연결됨 |
| #36411 | 메일러 FROM 필드에 non-ASCII 문자가 있으면 에러 발생 | 탈락 - issue/not-a-bug 라벨 |
| #35330 | RPM 패키지의 dnf 명령어가 Fedora 41+에서 작동하지 않음 | 선택 |
#35330을 선택한 이유는 명확합니다:
good first issue라벨이 달려있고, 다른 차단 라벨이 없습니다- 아직 아무도 PR을 올리지 않았습니다
- 문제와 해결 방법이 이슈에 구체적으로 명시되어 있습니다
- 데모 사이트에서 직접 재현할 수 있습니다
한 가지 더 강조하고 싶은 점은, 꼭 코드 변경만이 기여가 아니라는 것입니다. 이번에 제가 수정한 것도 Go 코드가 아니라 템플릿 파일과 안내 문구였습니다. 문서 개선, 번역, 오타 수정, UI 텍스트 변경 등도 모두 유효한 기여입니다. "나는 이 프로젝트의 언어를 잘 모르니까"라는 이유로 망설이고 있다면, 코드 외적인 부분부터 시작하는 것도 좋은 방법입니다.
이슈 선택이 기여의 절반입니다. 코드를 잘 짜는 것보다 좋은 이슈를 고르는 것이 훨씬 중요합니다.
이슈 분석: #35330
문제 상황
Gitea의 패키지 레지스트리는 RPM 저장소를 추가하는 명령어를 안내합니다. 그런데 이 명령어가 최신 Fedora에서 작동하지 않는 문제였습니다.
# 기존 안내 명령어 (RHEL/Rocky Linux 9에서만 작동)
dnf config-manager --add-repo https://example.com/rpm.repoCode language: Bash (bash)Fedora 41부터 DNF5가 기본 패키지 매니저로 채택되면서 명령어 문법이 변경되었습니다:
# Fedora 41+에서 기존 명령어 실행 시
$ dnf config-manager --add-repo https://example.com/rpm.repo
Unknown argument "--add-repo" for command "config-manager"Code language: Bash (bash)DNF5에서는 다른 문법을 사용해야 합니다:
# DNF5 문법 (Fedora 41+)
dnf config-manager addrepo --from-repofile=https://example.com/rpm.repoCode language: Bash (bash)수정 대상 파일 찾기
코드베이스에서 관련 파일을 검색했습니다:
grep -r "config-manager" --include="*.ini" --include="*.tmpl" --include="*.md" .Code language: Bash (bash)결과는 단 하나:
./templates/package/content/rpm.tmpl:dnf config-manager --add-repo ...Code language: Bash (bash)템플릿 파일 하나만 수정하면 되는 간단한 작업이었습니다.
구현 과정
브랜치 생성
git fetch upstream
git checkout main
git pull upstream main
git checkout -b fix/issue-35330-dnf5-commandCode language: Bash (bash)첫 번째 시도: locale 키 추가 방식
기존 코드를 보니 배포판 이름이 locale(번역) 키로 관리되고 있었습니다. 패턴을 따라 Fedora용 번역 키를 추가하는 방식으로 구현했습니다.
options/locale/locale_en-US.json:
{
"packages.rpm.distros.redhat": "on RedHat based distributions",
"packages.rpm.distros.fedora": "on Fedora (dnf5)",
"packages.rpm.distros.suse": "on SUSE based distributions"
}Code language: JSON / JSON with Comments (json)templates/package/content/rpm.tmpl:
# {{ctx.Locale.Tr "packages.rpm.distros.redhat"}}
{{- range $group := .Groups}}
dnf config-manager --add-repo <origin-url>/{{$.PackageDescriptor.Owner.Name}}/rpm{{$group}}.repo
{{- end}}
# {{ctx.Locale.Tr "packages.rpm.distros.fedora"}}
{{- range $group := .Groups}}
dnf config-manager addrepo --from-repofile=<origin-url>/{{$.PackageDescriptor.Owner.Name}}/rpm{{$group}}.repo
{{- end}}Code language: Bash (bash)PR 생성
git add .
git commit -m "fix: add dnf5 command for Fedora in RPM package instructions"
git push origin fix/issue-35330-dnf5-commandCode language: Bash (bash)PR 설명에는 변경 내용과 배경을 명확하게 작성했습니다:
## Summary
Add support for Fedora 41+ which uses dnf5 with different command syntax.
## Changes
- Added new locale key for Fedora (dnf5)
- Added dnf5 command in RPM package template
Closes #35330Code language: plaintext (plaintext)코드 리뷰 대응
PR을 올리고 며칠 후 리뷰를 받았습니다. 두 가지 피드백이 있었습니다.
피드백 1: DNF5 대문자 표기
dnf5를 DNF5로 수정하라는 요청이었습니다. Wikipedia 등 공식 문서에서 DNF5가 정식 표기라는 것이 근거였습니다. 사소해 보이지만 오픈소스 프로젝트에서는 이런 세부 사항도 중요하게 다룹니다.
피드백 2: 번역 키 대신 하드코딩
locale 번역 키를 사용하지 말고, 템플릿에 # Fedora 41+ (DNF5)를 직접 하드코딩하라는 피드백이었습니다. 배포판 이름과 툴체인 이름은 번역 대상이 아니라는 이유였습니다.
이 피드백이 핵심이었습니다. 저는 기존 코드 패턴(locale 키)을 그대로 따랐지만, 리뷰에서 더 나은 접근법을 알게 된 것입니다.
생각해보면 당연합니다:
- "Fedora"를 한국어로 "페도라"라고 번역하지 않습니다
- "DNF5"는 어떤 언어에서도 "DNF5"입니다
- 고유명사는 번역 시스템을 통할 이유가 없습니다
기존 패턴이 항상 최선은 아니라는 것을 배웠습니다.
최종 수정
locale 키를 삭제하고 템플릿에 직접 하드코딩했습니다:
# Fedora 41+ (DNF5)
{{- range $group := .Groups}}
{{- if $group}}{{$group = print "/" $group}}{{end}}
dnf config-manager addrepo --from-repofile=<origin-url>/{{$.PackageDescriptor.Owner.Name}}/rpm{{$group}}.repo
{{- end}}Code language: plaintext (plaintext)git add .
git commit -m "refactor: hardcode Fedora label instead of locale key"
git push origin fix/issue-35330-dnf5-commandCode language: Bash (bash)기존 PR에 새 커밋이 자동으로 추가되었고, 리뷰어들이 승인해주었습니다.
결과
두 명의 메인테이너 승인을 받아 머지되었습니다.
| 개선 전 | 개선 후 | |
|---|---|---|
| RHEL/Rocky (DNF4) | 정상 작동 | 정상 작동 |
| Fedora 41+ (DNF5) | Unknown argument 에러 | 정상 작동 |
템플릿 5줄 수정이 전부였지만, Fedora 사용자들이 Gitea 패키지 레지스트리를 사용할 때 겪던 불편함을 해결했습니다.
추가로 알아두면 좋은 점
RHEL도 결국 DNF5로 전환됩니다
현재 RHEL/Rocky Linux는 DNF4를 사용하지만, RHEL 10(2025 예정)부터 DNF5로 전환됩니다. 다만 RHEL 9 → 10 마이그레이션이 본격화되는 것은 2028년경으로 예상되어, 당분간은 두 버전을 모두 안내하는 현재 방식이 적절합니다.
오픈소스 기여 시 알아두면 좋은 에티켓
- 이슈에 먼저 댓글을 남기세요: "이 이슈를 작업해도 될까요?"라고 물어보면 중복 작업을 피할 수 있습니다
- 커밋 메시지 컨벤션을 확인하세요: Gitea는
fix:,feat:,refactor:같은 Conventional Commits를 사용합니다 - backport 라벨을 확인하세요: 메인테이너가
backport/v1.25같은 라벨을 달면 자동으로 백포트 PR이 생성됩니다
마무리
핵심을 정리하면 이렇습니다:
- 이슈 선택이 절반이다 -
good first issue라벨, PR 유무, 차단 라벨을 반드시 확인하세요 - 기존 패턴을 따르되 맹목적으로 따르지 마세요 - 코드 리뷰에서 더 나은 방법을 배울 수 있습니다
- 작은 기여도 의미 있다 - 5줄 수정으로도 실제 사용자 문제를 해결할 수 있습니다
오픈소스 기여는 생각보다 어렵지 않습니다. 완벽한 코드를 짜야 한다는 부담을 내려놓고, good first issue부터 시작해보세요. 메인테이너들은 생각보다 친절하고, 코드 리뷰 과정에서 배우는 것이 많습니다.
관련 링크:
조회수: 0