洪 民憙 (Hong Minhee)

안녕하세요. 오픈 소스 컨트리뷰션 아카데미 참여형 프로그램에서 Fedify 프로젝트를 함께 할 멘토 홍민희입니다.

Fedify 프로젝트에 참여하시게 된 것을 진심으로 환영합니다. 본 문서에서는 여러분이 앞으로 Fedify 프로젝트에 기여하기 위해서 알고 준비해야 하는 것들을 정리했습니다. 조금 긴 내용이 될 수도 있지만, 차근차근 읽어보시고 따라해야 할 과제는 따라해 주시기 바랍니다. 본 문서에 나온 과제들은 본격적인 기여를 위해 반드시 선행되어야 합니다.

소통 채널

가장 먼저 해야 할 것은 Fedify 프로젝트의 Discord 서버에 입장하는 것입니다. 만약 아직 Discord 계정이 없다면 하나 만드세요. 꽤 많은 오픈 소스 프로젝트들이 Discord에서 소통을 합니다. Discord 계정을 만들어 두면 앞으로 다양한 오픈 소스 프로젝트에 기여할 때 쓸모가 많을 것입니다.

Fedify 프로젝트의 Discord 서버에 입장하면, 다음과 같은 질문이 뜹니다:

그러면 한국어를 포함해 자신이 이해할 수 있는 언어들을 선택하시면 됩니다. 그러면 여러 채널들이 보이게 되는데, 그 중에서 여러분이 주로 이용하게 될 채널은 #fedify-dev-ko 채널입니다.

본 문서를 읽고 따라하면서 중간에 어려움이 있거나 막히는 부분이 있으면 해당 채널에서 편하게 질문하시면 됩니다.

프로젝트 관련해서 궁금한 점은 사소한 것이라도 Discord 서버에서 질문 주세요. “시간이 날 때 천천히 해결해야지”보다는 일단 물어보는게 낫습니다. 특히 초반의 많은 문제는, 보통 질문을 많이 하면 빨리 해결됩니다. 시간을 정해두세요. 이를테면 30분으로 정했으면 30분 내로 해결이 안되면 일단 질문을 합시다.

연합우주(fediverse)란?

Fedify 프로젝트가 어떤 프로젝트인지 이해하기 위해서는, 우선 페디버스(fediverse), 즉 한국어로 연합우주에 대해 기본적인 이해를 갖출 필요가 있습니다.

종래의 중앙집권적인 SNS들은 크게 두 가지 특징이 있습니다. 첫째로, SNS에 올리는 사용자들의 모든 데이터를 특정 기업이 사유한다는 것입니다. 둘째로, 서로 다른 SNS끼리는 소통할 수 없다는 것입니다. 특히, 두번째 특징은 이메일을 생각해 보면 아주 자연스러운 것은 아니라는 것을 알 수 있습니다. 네이버 메일을 쓰는 사람이 Gmail을 쓰는 사람과 소통할 수 없을까요? 그렇지 않지요. 하지만 Instagram 사용자는 X (舊 Twitter) 사용자와 소통할 수 없습니다.

이러한 문제를 해결하고자 나온 대안 SNS들이 있습니다. Mastodon이나 Pixelfed 같은 것들이 그렇습니다. 그리고 이러한 SNS들은 누구라도 자신의 서버에 설치가 가능합니다. 실제로 홈 서버에서 돌아가는 Mastodon 서버도 꽤 많습니다. 물론, 직접 서버를 운영하고 싶지 않은 대부분의 사람들에게는 대형 서버라는 선택지도 있습니다. 이를테면, Mastodon 서버 중에서 가장 사용자가 많은 서버인 mastodon.social은 Mastodon 개발 팀이 직접 운영하는 서버입니다.

하지만 이런 의문이 드실 수 있습니다. 자신의 홈 서버에 Mastodon을 설치해봤자 혼자 쓰는 일기장이 아닌가? 사실, Mastodon 서버들은 서로 소통이 가능합니다. 마치 이메일과도 같습니다. 자신의 홈 서버에 이메일 서버를 설치하여 자신만의 이메일 주소를 만들어도, 네이버 메일이나 Gmail과 서로 메일을 주고 받을 수 있는 것처럼요. 실제로, Mastodon의 계정 이름은 이메일 주소와 비슷하게 생겼습니다:

@username@server.com

이렇게 서로 다른 Mastodon 서버끼리 소통할 수 있도록 고안된 표준이 바로 ActivityPub 프로토콜입니다. 참고로, 이 ActivityPub 프로토콜은 Mastodon 프로젝트가 독자적으로 정한 게 아니라, W3C에서 웹 표준으로 정한 것입니다. 따라서 Mastodon 뿐만 아니라, Pixelfed 등 ActivityPub을 구현하는 다른 소프트웨어들도 서로 소통이 됩니다. Mastodon에서 Pixelfed로 댓글 다는 것도 되고, Pixelfed 사용자가 Mastodon 사용자를 팔로하는 것도 됩니다.

이렇게 서로 다른 SNS 소프트웨어, 사로 다른 서버끼리 자유롭게 소통이 가능한 구조를 연합(federation)이라고 부릅니다. 어떻게 보면, 이렇게 연합된 서로 다른 SNS들을 모두 합쳐서 하나의 SNS라고 볼 수도 있습니다. 이를 부르는 말이 바로 연합우주, 페디버스입니다.

연합우주는 현재도 꾸준히 커 가고 있습니다. 최근에는 Meta의 Threads도 ActivityPub을 구현하게 되었고, WordPress도 ActivityPub 플러그인을 공식적으로 개발했습니다. 특히, 기존의 연합우주 소프트웨어들은 각자의 서버에 직접 설치할 수 있는 오픈 소스 소프트웨어였던 것에 반해, Threads는 오픈 소스가 아님에도 ActivityPub을 구현했다는 점에서 상당히 이례적이라고 할 수 있습니다. 이런 방식의 연합도 가능하다는 것이죠.

JavaScript와 TypeScript

Fedify 프로젝트는 TypeScript로 작성되어 있습니다. TypeScript는 JavaScript에 정적 타입 검사를 추가한 언어로, 런타임에 버그를 발생시키는 잘못된 코드를 코드 작성 시에 미리 알 수 있도록 도와줍니다. TypeScript를 이해하려면 먼저 JavaScript를 이해해야 합니다.

아직 JavaScript에 익숙하지 않으신 분들은 《모던 JavaScript 튜토리얼》의 파트 1을 읽고 따라해 볼 것을 권합니다. 파트 2 이후의 내용은 Fedify 프로젝트에 기여하는 데에 크게 필요하지 않으므로 읽지 않으셔도 좋습니다.

JavaScript에는 어느 정도 익숙하지만 아직 TypeScript에 익숙하지 않으신 분들께는, 《The TypeScript Handbook》을 읽고 따라해 볼 것을 권합니다. 참고로 핸드북 페이지 우측 상단에 한국어 번역으로 가는 링크가 있습니다.

사실 오픈 소스 프로젝트에 기여하기 위해 반드시 그 프로젝트에서 쓰이는 언어를 속속들이 깊게 이해해야 하는 건 아닙니다. 기여할 때 필요한 만큼만 이해해도 좋으니, 어느 정도 언어 문법에 익숙해졌다 싶으면 실제 Fedify 코드를 읽는 것을 좀 더 추천합니다. 코드를 읽다가 이해가 안 되는 부분이 있으면 해당 언어 문법에 대해 따로 조사하는 식으로 익히시는 게 더 효율적입니다. 정 이해가 안 되는 경우에는 부담 없이 Fedify 프로젝트 Discord 서버의 #fedify-dev-ko 채널에서 질문해 주세요.

Fedify란?

여러분은 웹 서버 애플리케이션을 만들 때 HTTP를 직접 구현하시나요? 아마도 대부분은 그렇지 않을 겁니다. 그러기엔 할 게 너무 많기 때문이죠. 대신 우리는 대부분 Express나 Next.js, Django 같은 웹 프레임워크를 이용해서 개발하게 됩니다.

마찬가지로, 연합우주 SNS 소프트웨어를 구현하려고 할 경우, ActivityPub을 바닥부터 구현하기에는 너무 할 게 많습니다. 따라서 개발을 쉽게 해 줄 프레임워크가 필요한데, 그게 바로 Fedify입니다.

어떤 오픈 소스 프로젝트든 간에, 해당 프로젝트에 기여하기 위해서는 먼저 그 소프트웨어를 써보고 기본적인 기능들을 숙지해야 합니다. 써보지도 않은 소프트웨어에 기여를 하는 것은 무리입니다. 여러분도 Fedify에 기여하기에 앞서 Fedify를 써 볼 필요가 있습니다.

Fedify는 연합우주 소프트웨어를 만드는 도구이므로, Fedify를 사용한다고 하면 연합우주 소프트웨어를 만들어 본다는 뜻이 됩니다. Fedify를 사용하여 작은 ActivityPub 서버 소프트웨어를 만들어 보세요. Fedify를 써 보면서 이해가 안 가거나 중간에 막히는 게 있다면 Discord 서버의 #fedify-help-ko 채널에서 질문하세요.

저장소 포크 및 클론

git config --global core.autocrlf false

Fedify의 GitHub에 저장소가 올라가 있습니다. 해당 저장소를 각자 포크(fork)하신 뒤, 포크한 저장소를 로컬에 클론하세요. 클론하신 뒤, 클론한 로컬 저장소 안에 들어가 업스트림 저장소를 리모트로 추가하시는 것을 권합니다:

git remote add upstream https://github.com/fedify-dev/fedify.git
git fetch upstream
git pull --set-upstream upstream main

개발 환경 설정

Fedify의 개발 환경 설정은 일반적인 JavaScript 프로젝트들에 비해 조금 복잡한 편입니다. Node.js 이외에도 Deno와 Bun 등 여러 런타임을 지원해야 하기 때문인데요. Fedify의 개발을 위해서는 다음 소프트웨어가 시스템에 모두 설치되어 있어야 합니다:

• Node.js v22 이상
• Deno v2 이상
• Bun 최신 버전
• pnpm 최신 버전

하나하나 직접 설치하셔도 좋습니다만, 귀찮으시다면 mise라는 개발 환경 설정 소프트웨어를 이용하는 것을 권합니다. mise는 정말 다양한 방법으로 설치가 가능합니다:

sudo pacman -S mise      # Arch Linux
brew install mise        # macOS
winget install jdx.mise  # Windows
# 이 외에도 다양한 플랫폼 지원

설치하고 나서 PATH 환경 변수에 mise가 관리하는 소프트웨어들을 추가하도록 mise를 활성화해야 합니다. 활성화하는 방법은 어떤 셸을 사용하느냐에 따라 다릅니다:

zsh

echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc"
. "${ZDOTDIR-$HOME}/.zshrc"

Bash

echo 'eval "$(mise activate bash)"' >> ~/.bashrc
. ~/.bashrc

PowerShell

echo 'mise activate pwsh | Out-String | Invoke-Expression' >> $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
. $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1

mise를 설치하셨다면, 로컬 저장소 안에 들어가 다음 명령어로 필요한 모든 소프트웨어를 한 번에 설치하실 수 있습니다:

mise install --yes

위 명령어를 실행하면 아래와 같이 Fedify 저장소 안에 들어있는 mise 설정 파일을 신뢰하겠냐는 프롬프트가 뜹니다. Yes를 선택해 주세요:

mise config files in ~/fedify are not trusted. Trust them?


   Yes     No     All  

←/→ toggle • y/n/a/enter submit

개발 환경이 잘 설정되었는지 확인하기 위해 Fedify의 전체 테스트 스위트를 실행해 봅시다. 첫 실행 시 통상 5분 정도 소요됩니다:

deno task test-all

Git 훅도 설치합니다:

deno task hooks:install

마지막으로 실제 편집 환경을 구성해야 합니다. 본 문서에서는 Visual Studio Code를 사용하는 것을 가정하겠습니다만, 같은 Visual Studio Code 계열인 Cursor나 Windsurf에서도 과정은 대동소이합니다.

우선 로컬 저장소 안에서 code 명령어를 통해 Visual Studio Code를 띄웁니다:

code .     # Visual Studio Code를 사용하는 경우
cursor .   # Cursor를 사용하는 경우
windsurf . # Windsurf를 사용하는 경우

Visual Studio Code 창이 뜨면, 화면 가운데에 다음과 같은 프롬프트 창이 뜹니다:

프롬프트에서 예, 작성자를 신뢰합니다 버튼을 선택합니다. 그러면 오른쪽 아래에 다음과 같은 작은 프롬프트 창이 뜹니다:

프롬프트에서 설치 버튼을 선택합니다. 그러면 화면 가운데에 다음과 같은 프롬프트 창이 뜹니다:

프롬프트에서 게시자 신뢰 및 설치를 선택합니다. 그러면 Visual Studio Code에 Fedify 개발에 필요한 확장들이 설치되게 됩니다.

이로써 Fedify 기여에 필요한 기본적인 개발 환경 설정이 끝났습니다.

JavaScript 런타임

Fedify는 Deno, Node.js, Bun 등 다양한 JavaScript 런타임을 지원해야 합니다. 과연 JavaScript 런타임이 뭘까요?

JavaScript는 비교적 작은 언어입니다. 여러분이 process.exit() 같은 메서드를 활용하신 적 있다면, 이는 JavaScript 자체의 기능이 아니라 Node.js라는 특정한 JavaScript 런타임이 제공하는 기능입니다. 마찬가지로, 웹 브라우저에서 제공하는 DOM API 역시 JavaScript 자체의 기능이 아니라 웹 브라우저라는 (일종의) JavaScript 런타임이 제공하는 기능이라고 볼 수 있습니다.

JavaScript 런타임은 기본적으로 다음과 같은 역할을 합니다:

• JavaScript 코드를 실제로 실행합니다.
• JavaScript 언어로 사용 가능한 런타임 API를 제공합니다. 런타임 API로는 console.log(), Node.js의 process.exit(), 웹 브라우저의 window.alert() 같은 것들이 있습니다.
• 모듈 시스템을 제공합니다. 예를 들어, Node.js는 node_modules/ 디렉터리 기반의 모듈 시스템을 제공하는 반면, Deno에서는 임포트 맵(import map) 기반의 모듈 시스템을 제공합니다. Node.js에서는 npm이나 pnpm, Yarn 등의 패키지 관리자를 사용해야 하지만, Deno나 Bun은 자체적인 패키지 관리자를 제공합니다. 웹 브라우저나 Cloudflare Workers는 패키지 관리자를 제공하지 않기 때문에 번들링이라는 과정을 거쳐야 합니다.

앞서 설명한 모든 것을 속속들이 이해해야 할 필요는 없습니다. 중요한 것은, 같은 JavaScript라고 하더라도 어느 런타임에서 실행하냐에 따라 상당히 다른 방식으로 언어를 사용해야 한다는 점입니다.

그러면 Fedify 프로젝트는 다양한 JavaScript 런타임을 어떻게 동시에 다 지원할 수 있을까요? 크게 두 가지 방법이 있습니다:

1. 지원해야 하는 JavaScript 런타임 모두에서 공통적으로 지원하는 API만을 사용합니다.
2. 런타임에 따라 다른 코드를 실행하도록 코드를 여러 벌 작성합니다.

Fedify 프로젝트는 두 가지 방법 모두 사용하고 있으며, 지원하는 모든 JavaScript 런타임에서 테스트 스위트를 실행해서 Fedify의 모든 기능이 각 JavaScript 런타임에서 잘 동작하는지를 검사합니다.

Fedify 저장소의 구조

2025년 7월 현재, Fedify 프로젝트의 저장소는 다음과 같은 구조로 되어 있습니다:

• fedify/ — Fedify의 핵심인 @fedify/fedify 패키지입니다. 이 패키지는 Deno, Node.js, Bun, Cloudflare Workers 환경에서 동작합니다.
• cli/ — Fedify 사용자들을 위한 CLI 개발 도구인 @fedify/cli 패키지입니다. 이 패키지는 Deno로만 작성됩니다.
• amqp/ — AMQP/RabbitMQ 드라이버인 @fedify/amqp 패키지입니다.
• express/ — Express 프레임워크와의 연동 모듈인 @fedify/express 패키지입니다.
• h3/ — h3 프레임워크와의 연동 모듈인 @fedify/h3 패키지입니다.
• postgres/ — PostgreSQL 드라이버인 @fedify/postgres 패키지입니다.
• redis/ — Redis 드라이버인 @fedify/redis 패키지입니다.
• docs/ — Fedify의 문서가 포함되어 있습니다. https://fedify.dev/ 웹사이트의 소스 코드입니다. VitePress로 구축되어 있습니다.
• examples/ — 이름 그대로 Fedify를 사용하는 예제 프로젝트들이 들어 있습니다.
• scripts/ — 프로젝트 관리를 위한 스크립트들이 들어 있습니다. 대부분의 경우 건드릴 일이 없을 겁니다.

여러분은 주로 fedify/ 디렉터리 및 cli/ 디렉터리에서 작업을 하게 될 것입니다.

린트와 테스트

여느 오픈 소스 프로젝트들이 그렇듯, Fedify 프로젝트도 나름의 코딩 컨벤션과 규칙들이 있습니다. 다행히 이들 대부분은 커밋하기 전에 기계적으로 검사가 가능합니다. 다음 명령어는 현재 프로젝트의 코드가 코딩 컨벤션을 잘 지키고 타입 오류가 없는지 검사합니다:

deno task check

다음 명령어는 코드를 코딩 컨벤션에 맞게 알아서 서식화합니다:

deno fmt

앞서 언급한 것처럼, 다음 명령어는 Fedify 프로젝트의 전체 테스트 스위트를 실행하고 필요한 검사를 수행합니다. 풀 리퀘스트를 올리기 전에 한 번 실행해 보십시오:

deno task test-all

@fedify/fedify 패키지를 수정했을 경우, 수정과 관련된 일부 테스트 코드만 빠르게 실행해 보고 싶을 수 있습니다. 그럴 때는 다음과 같이 -f @fedify/fedify 옵션과 --filter 옵션을 함께 활용해 보세요 (태스크 이름이 test-all이 아니라 test임에 주의하세요):

deno task -f @fedify/fedify test --filter verifyRequest

혹은 -f @fedify/fedify 옵션을 쓰는 대신 직접 fedify/ 디렉터리 안에서 deno task test 명령어를 사용하셔도 됩니다:

cd fedify/
deno task test --filter verifyRequest

참고로 --filter 옵션은 테스트 케이스 이름을 부분 문자열로 검색합니다. 이를테면, 다음과 같은 테스트가 있을 경우:

test("anArbitraryTest", () => {
  // … 생략 …
});

다음과 같은 방식으로 모두 실행이 가능합니다:

deno task -f @fedify/fedify test --filter anArbitraryTest
deno task -f @fedify/fedify test --filter   Arbitrary
deno task -f @fedify/fedify test --filter            Test

앞서 설명한 deno task test 명령어는 Deno 런타임에서 테스트 스위트를 실행합니다. Node.js에서도 잘 돌아가나 확인하기 위해서는 Node.js 런타임에서도 테스트 스위트를 실행해 봐야 합니다. fedify/ 디렉터리 안쪽에서 pnpm test 명령어를 통해 Node.js에서 테스트 스위트를 돌려 볼 수 있습니다:

cd fedify/
pnpm test

일부 테스트만 빠르게 실행해 보고 싶을 경우 --test-name-pattern 옵션을 활용하세요:

pnpm test --test-name-pattern verifyRequest

Bun에서도 잘 돌아가는지 확인하려면 fedify/ 디렉터리 안쪽에서 pnpm test:bun 명령어를 사용하세요:

pnpm test:bun

일부 테스트만 빠르게 실행해 보고 싶을 경우 마찬가지로 --test-name-pattern 옵션을 활용하세요:

pnpm test:bun --test-name-pattern verifyRequest

마지막으로, Cloudflare Workers에서도 잘 돌아가는지 검사해야 합니다. 이 경우에는 pnpm test:cfworkers 명령어를 활용하세요:

pnpm test:cfworkers

일부 테스트만 빠르게 실행해 보고 싶을 경우 인자로 부분 문자열 키워드를 넘기면 됩니다:

pnpm test:cfworkers verifyRequest

사실, 앞서 설명했던 deno task test-all 명령어는 한 번에 Deno, Node.js, Bun, Cloudflare Workers 모두에서 테스트 스위트를 실행하는 명령어입니다.

@fedify/cli: Fedify CLI 도구

@fedify/cli 패키지는 Fedify를 이용하여 ActivityPub 서버를 구현하는 개발자들을 위한 CLI 편의 도구로서, 주로 ActivityPub 서버 개발을 할 때 디버그나 테스트를 위해 필요한 기능들을 제공합니다. 라이브러리 패키지인 @fedify/fedify와 다르게 @fedify/cli는 패키지는 애플리케이션이기 때문에 코드를 수정한 뒤 바로 사용해 볼 수가 있습니다. 또한, 굳이 여러 런타임을 지원할 필요가 없기 때문에 Deno 환경만 신경쓰면 됩니다.

그런 이유로, @fedify/cli 패키지는 처음 기여하기에 좋습니다. 참고로 @fedif/cli는 CLI 애플리케이션 프레임워크로 Cliffy를 사용하고 있으니, 관련해서 궁금한 게 있다면 Cliffy 문서를 참고해 주세요.

일감 찾기

대부분의 오픈 소스 프로젝트는 할 일을 이슈 트래커에서 관리합니다. Fedify 역시 GitHub에서 제공하는 이슈 트래커로 할 일들을 관리하고 있습니다. 특별한 이유가 없는 한, 이슈는 기본적으로 영어로 작성되거나, 적어도 영어가 병기되어야 합니다. 영어가 익숙치 않은 분들은 Kagi 번역 등을 활용하시면 될 것 같습니다. 언어 때문에 어려우신 분은 멘토에게 도움을 청하세요.

이슈는 크게 세 종류로 나뉩니다:

피처 (feature)

말 그대로 새로운 기능을 뜻합니다.

버그 (bug)

기존에 있던 기능의 오작동을 뜻합니다.

태스크 (task)

신기능이나 버그 이외의 작업들을 가리킵니다. 예를 들면, 문서 수정 등이 여기에 속합니다.

미분류 (no type)

아직 분류되지 않은 이슈들인데, 이슈는 어떻게든 분류되어야 하므로 보통은 없습니다.

위의 분류와는 별개로, Fedify 이슈 트래커에서는 레이블을 구조화하여 활용하고 있습니다. 대부분의 레이블은 범례/레이블 이름 형식을 따르며, 대표적으로는 다음과 같은 것들이 있습니다:

difficulty/beginner

쉬운 난이도

good first issue

처음 기여하는 사람에게 적합

help wanted

도움 필요

type/documentation

문서 관련

여기서 여러분이 가장 주목하셔야 할 레이블은 바로 good first issue입니다. 해당 레이블이 붙은 이슈는 처음 기여하는 사람에게 적합하기 때문에, 여러분의 첫 기여 때 할 일을 찾을 때 도움이 됩니다. 이슈들을 찬찬히 읽어보시고 해 볼 만한 일감을 고르세요. 이슈를 읽어도 이해가 안 될 경우에는 댓글로 질문을 남기거나 멘토에게 질문하세요.

기여해 볼 이슈를 찾으셨다면, 해당 이슈를 이미 다른 사람이 진행중인지 확인하세요. 아무도 진행하고 있지 않다면 진행하겠다는 댓글을 이슈에 달아주세요.

추가 정보 및 질문

본 문서에서 다루지 못한 내용도 많이 있을 것입니다. 아래 문서들은 부족한 부분을 좀 더 보충해 줄 수 있습니다:

• CONTRIBUTING.md
• Fedify 문서

본 문서를 읽다가 혹은 읽고 나서도 궁금한 점이 있다면 얼마든지 멘토에게 질문해 주세요. Discord 서버에서 질문하셔도 좋고, GitHub Discussions에 질문 글을 올리셔도 좋습니다.

🎉 Excited to announce that #Fedify is now on Open Collective! Support the project's development starting at:

• Backer (from $5/mo)
• Supporter (from $25/mo)
• Sponsor (from $100/mo)
• Corporate Sponsor (from $500/mo)
• Custom donations welcome

Your support will help us maintain and improve Fedify. Check it out here:

https://opencollective.com/fedify

#OpenCollective #support #backing #sponsor #donation