#mentoring

KDE

@kde@floss.social

Season of KDE 2026 kicks off with 25 volunteers working on 21 projects.

SoK is KDE's mentorship program that introduces new contributors to Free Software. This year our mentees will help improve the state of Plasma, KDE Connect, KDE's games, KDE Eco, translations, KDE's websites, internal data collection and more.

https://mentorship.kde.org/blog/2026-01-21-sok-26-welcome/

#mentoring #FreeSoftware #OpenSource

ALT text details

A bunch of saplings in pots overlaid with the KDE mentorship logo (a gear with a seed over one of its teeth) and the words "KDE Mentorship" below it.

Gustavo A. R. Silva

@gustavoars@fosstodon.org

I talked for more than two hours (135 mins to be precise) about upstream Linux kernel hardening at Okayama University this afternoon. 🐧👨🏽‍💻🎙

I just uploaded my slides here: https://embeddedor.com/blog/presentations/#Enhancing_spatial_safety_Better_array-bounds_checking_in_C_and_Linux_Okayama_University_%E2%80%93Guest_talk

I really enjoyed the session. The students were amazing. They were well prepared and asked a lot of questions. 👏🏼👏🏼

#Linux #OpenSource #Education #Mentoring #Okayama #OkayamaUniversity

洪民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to 洪民憙 (Hong Minhee) :nonbinary:'s post

And just finished writing a comprehensive contributor guide for the #OSSCA mentees!

You can check it out here—it's Korean though: https://hackers.pub/@hongminhee/2025/ossca-fedify-contributors-guide.

It covers everything from setting up the #fediverse accounts and development environment to finding good first issues. While it's primarily for the OSSCA participants, anyone interested in contributing to @fedify is welcome to use it as a reference.

Ready to onboard the next wave of #ActivityPub developers!

#Fedify #fedidev #opensource #mentoring

洪民憙 (Hong Minhee)

@hongminhee@hackers.pub

안내

이 문서는 기본적으로 오픈 소스 컨트리뷰션 아카데미 참여형 프로그램을 진행하게 된 멘티들을 위한 것입니다만, Fedify 프로젝트에 기여하고 싶은 분들이라면 얼마든지 활용하셔도 좋습니다.

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

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

소통 채널

중요

OSSCA 자체 Discord 서버에도 초대되셨을 것입니다만, 그곳에서는 행사에 관한 이야기만 주로 하게 될 겁니다. 실제 기여와 개발에 관련된 이야기는 지금부터 설명할 Fedify 프로젝트의 Discord 서버에서 이뤄지게 됩니다.

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

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

What language do you speak? どの言語を話しますか？ 어떤 언어를 쓰시나요?

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

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

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

과제

Discord 서버에 입장하신 뒤, #fedify-dev-ko 채널에서 간단히 자기 소개를 해 주세요. 본인의 이름과 GitHub 아이디를 꼭 알려주시기 바랍니다.

권고

원활하고 즉시적인 소통을 위해서는 모바일 앱으로 알림을 받을 수 있어야 합니다. 본인의 스마트폰에 Discord 앱을 설치하고 로그인한 뒤, 알림을 허용해 주세요. 랩톱 및 데스크톱 환경에서도 Discord 앱을 설치하고 항상 실행해 두실 것을 권합니다.

권고

가능하다면 Discord 계정의 아바타를 GitHub 계정의 프로필 사진과 통일해 주세요. 멘티가 워낙 많기 때문에 누가 누군지 기억하기 어렵기 때문입니다. 특히, 아무런 이미지도 설정해 두지 않은 분들은 아무 그림이라도 좋으니 시인성을 위해 설정을 부탁드립니다.

연합우주(fediverse)란?

안내

이미 연합우주나 ActivityPub에 대해 익숙하신 분들은 설명은 건너 뛰시고 이 섹션 마지막의 과제만 하셔도 괜찮습니다.

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을 구현했다는 점에서 상당히 이례적이라고 할 수 있습니다. 이런 방식의 연합도 가능하다는 것이죠.

안내

연합우주에 관해 좀 더 자세히 알고 싶어지셨다면, 〈연합우주(fediverse)와 ActivityPub 프로토콜 이해하기: 개발자를 위한 가이드〉라는 글도 읽어보시면 좋습니다.

과제

아직 연합우주를 경험해 본 적 없다면, 계정을 하나 만들어 봅시다. 계정을 만들기 위해서는 어떤 소프트웨어를 쓸 지 먼저 정해야 합니다. Mastodon과 Misskey는 일종의 X처럼 단문을 중심으로 한 SNS입니다. Pixelfed는 Instagram처럼 사진을 중심으로 한 SNS입니다. Meta의 Threads도 있습니다. 현재 읽고 계시는 이 글이 올라온 Hackers' Pub도 사실은 연합우주의 일부로서, 소프트웨어 개발자들을 위한 SNS입니다. 이 중 어떤 것을 선택하시든 서로 소통하는 데에는 문제가 없습니다.

만약 Mastodon이나 Misskey, Pixelfed를 선택하셨다면, 서버를 고르셔야 합니다. (물론, 서버를 직접 구축하시는 것도 괜찮습니다. 아마 많은 걸 배우실 수 있을 겁니다.) 무슨 서버를 골라야 할 지 모르시겠다면, Mastodon의 경우 silicon.moe 서버를, Misskey의 경우 stella.place 서버를, Pixelfed의 경우 chueok.pics 서버를 권합니다.

만약 Threads를 고르셨다면, 서버를 고를 필요가 없습니다. Threads는 설치형 소프트웨어가 아니라 Meta에서 운영하는 상용 서비스이기 때문입니다. 다만, 설정에 가셔서 페디버스 공유 설정을 켜 주셔야 합니다.

만약 Hackers' Pub을 고르셨다면, 역시 서버를 고를 필요가 없습니다. 단 하나의 서버만 있기 때문입니다. 다만, 초대장이 필요하므로 멘토에게 초대장을 요청하시기 바랍니다.

과제

연합우주 계정이 생기셨다면, 이제 친구를 사귀어야 합니다. 다른 멘티들에게 계정 주소를 물어보고 서로 팔로를 해 보세요. 멘토도 팔로해 보세요. (멘토도 맞팔 하겠습니다.) 멘토의 연합우주 계정 주소는 @hongminhee@hackers.pub입니다.

계정 주소로 팔로하는 방법은 소프트웨어마다 조금씩 다르지만, 대부분의 경우 검색창에 주소를 입력하면 해당 계정이 보입니다. 계정이 보인다면 팔로 버튼을 누르면 됩니다.

과제

생성한 계정으로 멘토의 계정인 @hongminhee@hackers.pub을 멘션하여 글을 써 주세요. 글 내용은 뭐든 좋습니다.

JavaScript와 TypeScript

안내

이미 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 채널에서 질문하세요.

과제

Fedify를 배우고 써보는 가장 쉬운 방법은 튜토리얼을 읽고 따라하는 것입니다. Fedify 공식 튜토리얼의 한국어판인 〈나만의 연합우주 마이크로블로그 만들기〉를 읽고 그대로 따라서 진행하세요. 빠르면 하루, 느긋하게 하면 사흘 정도 걸립니다. 중간에 막히는 부분이 있으면 멘토에게 부담 없이 질문하세요.

저장소 포크 및 클론

주의

Windows 환경에서 작업하실 때는 (WSL을 사용하지 않는다면) Git의 core.autocrlf 설정을 꺼 주시기 바랍니다:

git config --global core.autocrlf false

안내

Fedify 프로젝트를 Windows 환경에서 개발할 수는 있지만, Linux나 macOS에 비해 편의성이 떨어지는 것도 사실입니다. 가능하면 WSL을 세팅하시고 WSL 안에서 작업하시는 걸 추천드립니다.

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

팁

대부분의 Linux의 경우 (또는 Windows의 WSL 안에서 작업하는 경우) 별 다른 설정을 하지 않았다면 bash를 쓰고 계실 것입니다. macOS를 쓰시고 별 다른 설정을 하지 않으셨다면 zsh을 쓰고 계실 것입니다. (WSL이 아닌) Windows의 경우에는 명령 프롬프트가 아닌 PowerShell 안에서 작업하셔야 합니다.

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에서도 과정은 대동소이합니다.

경고

Visual Studio와 Visual Studio Code는 서로 전혀 다른 별개의 제품이니 주의하세요.

안내

여러분이 Emacs나 Vim의 독실한 신자라면 Visual Studio Code를 사용하고 싶지 않을 수 있습니다. 그런 경우, Deno의 공식 환경 설정 문서를 참고하여 Deno 랭귀지 서버를 설정해 주시기 바랍니다.

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

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

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

이 폴더에 있는 파일의 작성자를 신뢰합니까?

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

이 리포지토리에 대해 권장되는 Street Side Software, Red Hat 등의 확장을(를) 설치하시겠습니까?

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

게시자 “Street Side Software” 신뢰하고 다른 2?

프롬프트에서 게시자 신뢰 및 설치를 선택합니다. 그러면 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 런타임을 어떻게 동시에 다 지원할 수 있을까요? 크게 두 가지 방법이 있습니다:

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

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-all

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

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입니다. 해당 레이블이 붙은 이슈는 처음 기여하는 사람에게 적합하기 때문에, 여러분의 첫 기여 때 할 일을 찾을 때 도움이 됩니다. 이슈들을 찬찬히 읽어보시고 해 볼 만한 일감을 고르세요. 이슈를 읽어도 이해가 안 될 경우에는 댓글로 질문을 남기거나 멘토에게 질문하세요.

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

과제

처음 기여할 이슈를 찾아 이슈에 댓글을 달아주세요. 이슈를 못 찾겠다면 멘토에게 도움을 요청하세요. 멘토가 기여할 만한 일을 함께 찾아줄 수 있습니다.

안내

굳이 이슈 트래커에 이미 있는 이슈 중에서만 고를 필요는 없습니다. Fedify를 써 보면서 개선할 부분을 발견하셨다면, 그걸 이슈로 만들어서 직접 해결하셔도 좋습니다. 사실, 오픈 소스의 많은 이슈들이 이슈를 제기한 사람에 의해 해결됩니다.

추가 정보 및 질문

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

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

洪民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to 洪民憙 (Hong Minhee) :nonbinary:'s post

And just finished writing a comprehensive contributor guide for the #OSSCA mentees!

You can check it out here—it's Korean though: https://hackers.pub/@hongminhee/2025/ossca-fedify-contributors-guide.

Ready to onboard the next wave of #ActivityPub developers!

#Fedify #fedidev #opensource #mentoring

洪民憙 (Hong Minhee)

@hongminhee@hackers.pub

안내

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

소통 채널

중요

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

What language do you speak? どの言語を話しますか？ 어떤 언어를 쓰시나요?

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

과제

Discord 서버에 입장하신 뒤, #fedify-dev-ko 채널에서 간단히 자기 소개를 해 주세요. 본인의 이름과 GitHub 아이디를 꼭 알려주시기 바랍니다.

권고

연합우주(fediverse)란?

안내

이미 연합우주나 ActivityPub에 대해 익숙하신 분들은 설명은 건너 뛰시고 이 섹션 마지막의 과제만 하셔도 괜찮습니다.

@username@server.com

안내

과제

생성한 계정으로 멘토의 계정인 @hongminhee@hackers.pub을 멘션하여 글을 써 주세요. 글 내용은 뭐든 좋습니다.

JavaScript와 TypeScript

안내

이미 JavaScript와 TypeScript에 익숙하시다면 이 챕터는 넘기셔도 됩니다.

Fedify란?

과제

저장소 포크 및 클론

주의

Windows 환경에서 작업하실 때는 (WSL을 사용하지 않는다면) Git의 core.autocrlf 설정을 꺼 주시기 바랍니다:

git config --global core.autocrlf false

안내

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

개발 환경 설정

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

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

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와 Visual Studio Code는 서로 전혀 다른 별개의 제품이니 주의하세요.

안내

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

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

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

이 폴더에 있는 파일의 작성자를 신뢰합니까?

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

이 리포지토리에 대해 권장되는 Street Side Software, Red Hat 등의 확장을(를) 설치하시겠습니까?

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

게시자 “Street Side Software” 신뢰하고 다른 2?

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

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

JavaScript 런타임

Fedify는 Deno, Node.js, Bun 등 다양한 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는 패키지 관리자를 제공하지 않기 때문에 번들링이라는 과정을 거쳐야 합니다.

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

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

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/ 디렉터리에서 작업을 하게 될 것입니다.

린트와 테스트

deno task check-all

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

deno fmt

deno task test-all

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

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 도구

일감 찾기

중요

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

피처 (feature): 말 그대로 새로운 기능을 뜻합니다.
버그 (bug): 기존에 있던 기능의 오작동을 뜻합니다.
태스크 (task): 신기능이나 버그 이외의 작업들을 가리킵니다. 예를 들면, 문서 수정 등이 여기에 속합니다.
미분류 (no type): 아직 분류되지 않은 이슈들인데, 이슈는 어떻게든 분류되어야 하므로 보통은 없습니다.

difficulty/beginner: 쉬운 난이도
good first issue: 처음 기여하는 사람에게 적합
help wanted: 도움 필요
type/documentation: 문서 관련

안내

좀 더 자세히 확인하실 분은 전체 레이블 목록을 확인하세요.

과제

안내

추가 정보 및 질문

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

洪民憙 (Hong Minhee)

@hongminhee@hollo.social

Excited to share that I've joined #OSSCA (Open Source Software Contribution Academy) as a mentor for the @fedify project!

OSSCA is a national program run by South Korea's NIPA (National IT Industry Promotion Agency) through their Open Source Software Support Center, aimed at fostering the next generation of open source contributors.

We're currently in the process of selecting around 20 mentees who will start contributing to #Fedify once the selection is complete. I've been busy preparing good first issues to help them get started on their open source journey.