✏️ 1. 서론

개발자로서 오픈소스에 기여하는 일은 언젠가 꼭 해보고 싶은 목표 중 하나였습니다. 하지만 막상 시도하려고 하면, 어디서부터 시작해야 할지 막막한 것이 현실이었습니다.

그러던 중, 오픈소스 기여 방법을 안내해주는 커뮤니티를 알게 되었고, 그곳에서 멘토링 프로그램에 참여하게 되었습니다. 이슈를 찾고, 기여할 부분을 고민하며, 본격적으로 오픈소스의 세계에 발을 들이게 되었죠.

Kafka를 공부하던 어느 날, 문득 Spring Kafka의 내부 구현이 궁금해졌고, 자연스럽게 GitHub 저장소를 들여다보게 되었습니다. 거기서 발견한 하나의 이슈 — 작아 보이지만 사용자 혼란을 야기할 수 있는 문제 — 를 계기로 생애 첫 Pull Request를 만들게 되었고, 운 좋게도 머지되며 Spring Kafka의 공식 Contributor가 될 수 있었습니다.

이 글에서는 그 여정을 공유하며, 어떤 이슈를 발견하고 어떻게 기여했는지를 정리해보려 합니다. 오픈소스 기여를 꿈꾸지만 막연한 분들께 작게나마 도움이 되었으면 합니다.

✏️ 2. 본론

🤔 2.1. 이슈 선택 과정

이슈를 선정할 때 가장 중요하게 생각한 기준은 기여가 비교적 쉬운가?, 그리고 해당 프로젝트의 소스 코드를 깊이 이해하지 않더라도 수정이 가능한가? 였습니다.

이러한 기준에 따라 Apache 프로젝트, Spring 프로젝트 등 여러 오픈소스 저장소를 둘러보며 적절한 이슈를 찾기 시작했습니다.

처음에는 Apache Jackrabbit Oak 프로젝트에서 기여할 만한 이슈를 찾을 수 있었습니다. 자세한 내용은 뒤에서 설명하겠지만, 결과적으로 해당 PR은 머지되지 못했고, 다시 새로운 이슈를 찾아 나섰습니다.

그러던 중, Spring-Kafka 에서 KafkaTemplate Bean 이름 불일치 이슈 를 발견하게 되었고, 그 내용을 바탕으로 기여하게 되었습니다.

📚 2.2. 이슈: KafkaTemplate Bean 이름 불일치

Spring Kafka의 공식 문서에서는 @RetryableTopic 이 기본적으로 사용할 KafkaTemplate 빈의 이름을 defaultRetryTopicKafkaTemplate라고 명시하고 있습니다. 그러나 실제 @RetryableTopic 의 JavaDoc에서는 다음과 같이 설명하고 있었습니다.

* If not specified, a bean with name {@code retryTopicDefaultKafkaTemplate} or {@code kafkaTemplate} will be looked up.

즉, JavaDoc에는 retryTopicDefaultKafkaTemplate, 공식 문서에는 defaultRetryTopicKafkaTemplate라는 이름이 나와 있었고, 테스트 코드 일부도 JavaDoc 쪽 이름을 따라가고 있었습니다. 이로 인해 어떤 빈 이름을 사용해야 하는지 명확하지 않았습니다.

👉 해당 이슈는 Spring Kafka GitHub Issue #3514 에서 논의되었습니다.

‍💻 2.3. PR: JavaDoc 정정

먼저, @RetryableTopic 어노테이션 클래스의 JavaDoc을 공식 문서와 일치하도록 수정했습니다.

Before:

 * The bean name of the {@link org.springframework.kafka.core.KafkaTemplate} bean that
 * will be used to forward the message to the retry and Dlt topics. If not specified,
 * a bean with name {@code retryTopicDefaultKafkaTemplate} or {@code kafkaTemplate}
 * will be looked up.
 *
 * @return the kafkaTemplate bean name.

After:

 * The bean name of the {@link org.springframework.kafka.core.KafkaTemplate} bean that
 * will be used to forward the message to the retry and Dlt topics. If not specified,
 * a bean with name {@code defaultRetryTopicKafkaTemplate} or {@code kafkaTemplate}
 * will be looked up.
 *
 * @return the kafkaTemplate bean name.

bean 으로 retryTopicDefaultKafkaTemplate 대신 defaultRetryTopicKafkaTemplate 사용한다고 수정을 하였습니다.

이 수정으로 공식 문서와 JavaDoc이 일치하게 되었고, 실제 사용자들이 혼란 없이 올바른 빈 이름을 사용할 수 있게 되었습니다.

👉 Commit Message → Fix: Replace retryTopicDefaultKafkaTemplate with defaultRetryTopicKafkaTemplate in docs

💻 2.4. PR: 테스트 코드 정정

또한 테스트 코드 내에서도 잘못된 빈 이름 문자열을 직접 명시하고 있었습니다. RetryTopicConfigurationProviderTests 라는 테스트 클래스에서 사용 중이었는데, 이 부분은 상수 RetryTopicBeanNames.DEFAULT_KAFKA_TEMPLATE_BEAN_NAME 을 사용하도록 리팩터링했습니다.

Before:

@Test
void shouldProvideFromAnnotation() {

	// setup
	willReturn(kafkaOperations).given(beanFactory).getBean("retryTopicDefaultKafkaTemplate", KafkaOperations.class);

	// given
	RetryTopicConfigurationProvider provider = new RetryTopicConfigurationProvider(beanFactory);
	RetryTopicConfiguration configuration = provider.findRetryConfigurationFor(topics, annotatedMethod, bean);
	RetryTopicConfiguration configurationFromClass = provider
			.findRetryConfigurationFor(topics, null, AnnotatedClass.class, bean);
	// then
	then(this.beanFactory).should(times(0)).getBeansOfType(RetryTopicConfiguration.class);
	assertThat(configuration).isNotNull();
	assertThat(configurationFromClass).isNotNull();
}

@Test
void shouldProvideFromMetaAnnotation() {

	// setup
	willReturn(kafkaOperations).given(beanFactory).getBean("retryTopicDefaultKafkaTemplate", KafkaOperations.class);

	// given
	RetryTopicConfigurationProvider provider = new RetryTopicConfigurationProvider(beanFactory);
	RetryTopicConfiguration configuration = provider.findRetryConfigurationFor(topics, metaAnnotatedMethod, bean);
	RetryTopicConfiguration configurationFromClass = provider
			.findRetryConfigurationFor(topics, null, MetaAnnotatedClass.class, bean);
	// then
	then(this.beanFactory).should(times(0)).getBeansOfType(RetryTopicConfiguration.class);
	assertThat(configuration).isNotNull();
	assertThat(configuration.getConcurrency()).isEqualTo(3);
	assertThat(configurationFromClass).isNotNull();
	assertThat(configurationFromClass.getConcurrency()).isEqualTo(3);
}

After:

@Test
void shouldProvideFromAnnotation() {

	// setup
	willReturn(kafkaOperations).given(beanFactory).getBean(RetryTopicBeanNames.DEFAULT_KAFKA_TEMPLATE_BEAN_NAME, KafkaOperations.class);

	// given
	RetryTopicConfigurationProvider provider = new RetryTopicConfigurationProvider(beanFactory);
	RetryTopicConfiguration configuration = provider.findRetryConfigurationFor(topics, annotatedMethod, bean);
	RetryTopicConfiguration configurationFromClass = provider
			.findRetryConfigurationFor(topics, null, AnnotatedClass.class, bean);
	// then
	then(this.beanFactory).should(times(0)).getBeansOfType(RetryTopicConfiguration.class);
	assertThat(configuration).isNotNull();
	assertThat(configurationFromClass).isNotNull();
}

@Test
void shouldProvideFromMetaAnnotation() {

	// setup
	willReturn(kafkaOperations).given(beanFactory).getBean(RetryTopicBeanNames.DEFAULT_KAFKA_TEMPLATE_BEAN_NAME, KafkaOperations.class);

	// given
	RetryTopicConfigurationProvider provider = new RetryTopicConfigurationProvider(beanFactory);
	RetryTopicConfiguration configuration = provider.findRetryConfigurationFor(topics, metaAnnotatedMethod, bean);
	RetryTopicConfiguration configurationFromClass = provider
			.findRetryConfigurationFor(topics, null, MetaAnnotatedClass.class, bean);
	// then
	then(this.beanFactory).should(times(0)).getBeansOfType(RetryTopicConfiguration.class);
	assertThat(configuration).isNotNull();
	assertThat(configuration.getConcurrency()).isEqualTo(3);
	assertThat(configurationFromClass).isNotNull();
	assertThat(configurationFromClass.getConcurrency()).isEqualTo(3);
}

"retryTopicDefaultKafkaTemplate" 으로 되어있던 Bean 이름 부분을 RetryTopicBeanNames.DEFAULT_KAFKA_TEMPLATE_BEAN_NAME 로 변경하였습니다.

이를 통해 빈 이름도 변경하였고, 하드코딩된 문자열을 제거하면서, 상수를 사용하는 방식으로 코드의 일관성과 안정성을 확보했습니다. 추후 KafkaTemplate 빈 이름이 변경되더라도 상수만 수정하면 되므로 유지보수가 용이해졌습니다.

👉 Commit Message → Fix: Replace retryTopicDefaultKafkaTemplate with RetryTopicBeanNames.DEFAULT_KAFKA_TEMPLATE_BEAN_NAME in Test Code

그 결과, Spring Kafka 의 Contributor 가 되었고, 제 생의 첫 오픈 소스 기여에 성공하게 되었습니다.

해당 PR 내용을 확인하고 싶다면, Spring Kafka PR 기여 성공 해당 링크를 클릭하시기 바랍니다.

🤣 2.5. 배움: Apache Jackrabbit Oak 기여 실패 경험

위에서 언급하였지만, Spring Kafka 를 기여하기 전에, Apache Jackrabbit Oak 의 이슈를 하나 먼저 찾을 수 있었습니다.

💡 Apache Jackrabbit Oak ?
파일이나 문서 같은 데이터를 트리 구조로 저장하고 관리해주는 시스템입니다.
Java로 만들어졌고, Adobe Experience Manager(AEM) 같은 유명한 콘텐츠 관리 시스템에서 내부 저장소로 사용되고 있습니다.
예를 들면, 웹사이트에서 페이지를 만들거나 이미지를 업로드할 때, 그 데이터를 저장하는 데 Oak가 쓰일 수 있습니다.
파일이나 폴더를 디렉토리처럼 관리하고, 누가 언제 바꿨는지 기록도 남길 수 있어서, 문서 관리 시스템이나 CMS에 딱 맞는 구조입니다.

당시 이슈 내용은 다음과 같았는데

MAX_SEGMENT_SIZE 상수가 Segment와 SegmentDataUtil s에 중복 정의되어 있으니 하나로 공유 할 수 있게 해달라는 내용이었습니다.

Segment 라는 클래스에서 static final int MAX_SEGMENT_SIZE = 1 << 18; 로 되어있는 부분에 public 을 달아주고, 그걸 SegmentDataUtil 에서 사용 할 수 있게 해주는게 전부였습니다.

그래서 아래와 같이, 코드를 수정하려 PR 을 보냈습니다.

하지만 결과는 Merge 실패였습니다.

이유는 간단했습니다.

이미 저보다 먼저 해당 이슈를 캐치하고 PR 을 올린 사람이 있었기 때문이었습니다.

오픈 소스 생태계를 보면, 처음에는 잘 몰라서 실수 할 수 있는 2가지가 있습니다. 하나는 완료 된 이슈인데도 이슈가 Close 되어있지 않은게 있을 수 있다는 것입니다.

또 다른 하나는 누군가 해당 이슈를 해결하기 위해 Assign 을 받았는데, 그것을 가로채는 행동을 해서는 안된다는 것입니다.

보통은 이슈에 댓글로 본인이 해결하겠다고 리플을 달아두고 진행을 합니다. 그렇기 때문에, 어떠한 이슈를 해결하고자 한다면, 꼭 댓글에 본인이 해결하겠다는 의사를 밝히고, 진행하는 것이 좋습니다.

그리고 다른 사람이 진행을 하겠다고 댓글을 이미 남긴 상태라면, 그걸 가로채서는 안됩니다. 다만, 댓글이 달리고 한참이 지났는데도 해결이 되지 않은 이슈라면, 해당 이슈가 현재 해결 중인지, 그게 아니라면 내가 해결을 해도 되는지 댓글로 물어보고 진행을 하는 방향도 있습니다.

✏️ 3. 결론

이번 기여를 통해 Spring Kafka 문서와 코드의 불일치 문제를 해결하며, 보다 명확하고 유지보수하기 쉬운 기반을 마련하는 데 작은 보탬이 될 수 있었습니다.

비록 작고 사소한 변경처럼 보일 수 있지만, 실제 사용자 경험에 직접적인 영향을 줄 수 있다는 점에서 그 의미는 결코 작지 않았습니다. 무엇보다 오픈소스 생태계의 문화, 프로세스, 협업 방식을 실제로 체험하고 배울 수 있었던 값진 경험이었습니다.

오픈소스 기여를 어렵게만 느끼는 분들도 많겠지만, 완벽하게 아는 상태에서 시작하는 사람은 없습니다. 저 역시 문서 하나 고치고, 테스트 코드 한 줄 바꾸는 데서 시작했습니다.

작은 기여도 충분히 의미 있고, 오픈소스 커뮤니티는 그런 기여를 소중히 여깁니다.

👨 “중요한 건 완벽함이 아니라 시작입니다. 지금 여러분도 첫 발을 내디뎌보세요.”