모듈 릴리스·버전 관리 워크플로

모듈 릴리스·버전 관리 워크플로 (Module release and versioning workflow)

다른 개발자가 쓸 수 있도록 모듈을 개발한다면, 모듈을 사용하는 개발자들에게 신뢰할 수 있고 일관된 경험을 보장해 주는 워크플로를 따르는 것이 좋아요. 이 주제에서는 그 워크플로의 큰 단계들(high-level steps)을 설명합니다.

모듈 개발 전반에 대한 개요는 Developing and publishing modules를 참고하세요.

출처: Go 공식 문서

참고 자료 (See also)

  • 코드에서 외부 패키지를 그냥 사용하고 싶다면 Managing dependencies를 꼭 보세요.
  • 새 버전마다 모듈의 변경을 버전 번호로 알리게 됩니다. 자세한 내용은 Module version numbering을 참고하세요.

일반적인 워크플로 단계

다음 순서는 예시로 든 새 모듈에 대한 릴리스·버전 관리 워크플로 단계를 보여줘요. 각 단계에 대한 자세한 내용은 이 주제의 해당 섹션을 참고하세요.

  • 모듈을 시작하고, 개발자가 쓰기 쉽고 여러분이 유지보수하기 쉽도록 소스를 구성하세요. 모듈 개발이 정말 처음이라면 Tutorial: Create a Go module을 확인해 보세요. Go의 분산 모듈 게시 시스템에서는 코드를 어떻게 구성하는지가 중요해요. 자세한 내용은 Managing module source를 참고하세요.
  • 미게시 모듈의 함수를 호출하는 로컬 클라이언트 코드를 작성할 준비를 하세요. 모듈을 게시하기 전에는 go get 같은 명령을 쓰는 일반적인 의존성 관리 워크플로에서 그 모듈을 사용할 수 없어요. 이 단계에서 모듈 코드를 테스트하는 좋은 방법은, 호출하는 코드와 로컬 디렉터리에 있을 때 시도해 보는 것입니다. 로컬 개발에 대한 자세한 내용은 미게시 모듈에 대해 코딩하기를 참고하세요.
  • 모듈의 코드가 다른 개발자가 시험해 볼 준비가 되면, v0 사전 릴리스를 게시하기 시작하세요. 알파(alpha), 베타(beta)처럼요. 자세한 내용은 사전 릴리스 버전 게시하기를 참고하세요.
  • 안정성이 보장되지는 않지만 사용자가 시험해 볼 수 있는 v0을 릴리스하세요. 자세한 내용은 첫 번째 (불안정한) 버전 게시하기를 참고하세요.
  • v0 버전을 게시한 뒤에는 (그래야 하고, 그래요!) 계속해서 새 버전을 릴리스할 수 있습니다. 이 새 버전들에는 버그 수정(패치 릴리스), 모듈 공개 API에 대한 추가(마이너 릴리스), 심지어 호환성을 깨뜨리는 변경(breaking change)까지 포함될 수 있어요. v0 릴리스는 안정성이나 하위 호환성을 보장하지 않으므로, 그 버전들에서 호환성을 깨뜨리는 변경을 할 수 있습니다. 자세한 내용은 버그 수정 게시하기와 호환성을 깨지 않는 API 변경 게시하기를 참고하세요.
  • 안정적인 버전을 릴리스할 준비가 되면, 알파와 베타로 사전 릴리스를 게시합니다. 자세한 내용은 사전 릴리스 버전 게시하기를 참고하세요.
  • 첫 안정 릴리스로 v1을 릴리스하세요. 이것은 모듈의 안정성에 대한 약속(commitment)을 하기 시작하는 첫 릴리스입니다. 자세한 내용은 첫 안정 버전 게시하기를 참고하세요.
  • v1 버전에서 계속 버그를 고치고, 필요하면 모듈의 공개 API에 추가하세요. 자세한 내용은 버그 수정 게시하기와 호환성을 깨지 않는 API 변경 게시하기를 참고하세요.
  • 피할 수 없을 때는 호환성을 깨뜨리는 변경을 새 메이저 버전으로 게시하세요. v1.x.x에서 v2.x.x로의 메이저 버전 업데이트 같은 것은 모듈 사용자에게 매우 큰 방해가 되는 업그레이드일 수 있어요. 최후의 수단이어야 합니다. 자세한 내용은 호환성을 깨뜨리는 API 변경 게시하기를 참고하세요.

미게시 모듈에 대해 코딩하기

모듈이나 모듈의 새 버전을 개발하기 시작하면 아직 게시하지 않았을 거예요. 모듈을 게시하기 전에는 Go 명령으로 그 모듈을 의존성으로 추가할 수 없습니다. 그래서 처음에는, 다른 모듈에 있는 클라이언트 코드에서 미게시 모듈의 함수를 호출하려면 로컬 파일 시스템에 있는 모듈 사본을 참조해야 합니다.

클라이언트 모듈의 go.mod 파일에서 replace 지시문을 사용해 모듈을 로컬로 참조할 수 있어요. 자세한 내용은 Requiring module code in a local directory를 참고하세요.

사전 릴리스 버전 게시하기

사전 릴리스 버전을 게시해서 다른 사람들이 모듈을 시험해 보고 피드백을 주도록 할 수 있어요. 사전 릴리스 버전은 안정성을 보장하지 않습니다.

사전 릴리스 버전 번호에는 사전 릴리스 식별자가 붙어요. 버전 번호에 대한 자세한 내용은 Module version numbering을 참고하세요.

예시 두 개입니다:

v0.2.1-beta.1
v1.2.3-alpha

사전 릴리스를 제공할 때 염두에 둘 점은, 사전 릴리스를 사용하는 개발자들은 go get 명령으로 버전을 명시해 지정해야 한다는 것입니다. 기본적으로 go 명령은 요청한 모듈을 찾을 때 사전 릴리스 버전보다 릴리스 버전을 선호하기 때문이에요. 그래서 개발자들은 아래 예시처럼 사전 릴리스를 명시적으로 지정해서 받아야 합니다:

go get example.com/[email protected]

저장소에서 모듈 코드에 태그(tag)를 달아 사전 릴리스를 게시합니다. 태그에 사전 릴리스 식별자를 지정해요. 자세한 내용은 Publishing a module을 참고하세요.

첫 번째 (불안정한) 버전 게시하기

사전 릴리스 버전을 게시할 때와 마찬가지로, 안정성이나 하위 호환성을 보장하지는 않지만 사용자에게 모듈을 시험해 보고 피드백을 줄 기회를 주는 릴리스 버전도 게시할 수 있어요.

불안정한 릴리스는 버전 번호가 v0.x.x 범위인 것들입니다. v0 버전은 안정성이나 하위 호환성에 대한 보장이 없어요. 하지만 v1과 이후 버전으로 안정성을 약속하기 전에 피드백을 받고 API를 다듬을 방법을 제공해 줍니다. 자세한 내용은 Module version numbering을 참고하세요.

다른 게시 버전처럼, 안정적인 v1을 릴리스하기 위한 변경을 하면서 v0 버전 번호의 마이너·패치 부분을 올릴 수 있어요. 예를 들어 v0.0.0을 릴리스한 뒤, 첫 번째 버그 수정 묶음과 함께 v0.0.1을 릴리스할 수 있습니다.

예시 버전 번호입니다:

v0.1.3

저장소에서 모듈 코드에 태그를 달아 불안정한 릴리스를 게시하며, 태그에 v0 버전 번호를 지정합니다. 자세한 내용은 Publishing a module을 참고하세요.

첫 안정 버전 게시하기

첫 안정 릴리스는 v1.x.x 버전 번호를 갖게 됩니다. 첫 안정 릴리스는 여러분이 피드백을 받고, 버그를 고치고, 사용자를 위해 모듈을 안정화시켰던 사전 릴리스와 v0 릴리스에 이어집니다.

v1 릴리스로 여러분은 모듈을 사용하는 개발자들에게 다음을 약속하게 됩니다:

  • 그들은 자기 코드를 깨지 않고 메이저 버전의 이후 마이너·패치 릴리스로 업그레이드할 수 있다.
  • 모듈의 공개 API — 함수·메서드 시그니처를 포함해 — 에 대해 하위 호환성을 깨뜨리는 더 이상의 변경을 하지 않겠다.
  • 하위 호환성을 깨뜨릴 exported 타입을 제거하지 않겠다.
  • API의 미래 변경(예: 구조체에 새 필드 추가)은 하위 호환적이며 새 마이너 릴리스에 포함된다.
  • 버그 수정(예: 보안 수정)은 패치 릴리스에 포함되거나 마이너 릴리스의 일부로 제공된다.

참고: 첫 메이저 버전이 v0 릴리스일 수도 있지만, v0 버전은 안정성·하위 호환성 보장을 뜻하지 않아요. 결과적으로 v0에서 v1로 올릴 때는 v0 릴리스가 안정적이지 않다고 간주되므로 하위 호환성을 깨뜨리는 것에 신경 쓸 필요가 없습니다.

버전 번호에 대한 자세한 내용은 Module version numbering을 참고하세요.

안정 버전 번호 예시입니다:

v1.0.0

저장소에서 모듈 코드에 태그를 달아 첫 안정 릴리스를 게시하며, 태그에 v1 버전 번호를 지정합니다. 자세한 내용은 Publishing a module을 참고하세요.

버그 수정 게시하기

변경이 버그 수정에 국한된 릴리스를 게시할 수 있어요. 이를 패치 릴리스(patch release)라고 합니다.

패치 릴리스는 사소한 변경만 포함합니다. 특히 모듈의 공개 API에는 어떤 변경도 없어요. 소비하는 코드의 개발자들은 자기 코드를 바꿀 필요 없이 안전하게 이 버전으로 업그레이드할 수 있습니다.

참고: 패치 릴리스는 그 모듈 자신의 전이적 의존성(transitive dependency)을 패치 릴리스 이상으로 업그레이드하지 않도록 노력해야 해요. 그렇지 않으면 여러분 모듈의 패치로 업그레이드하는 누군가가 자기들이 사용하는 전이적 의존성에서 더 침습적인 변경을 실수로 끌어들일 수 있습니다.

패치 릴리스는 모듈 버전 번호의 패치 부분을 올립니다. 자세한 내용은 Module version numbering을 참고하세요.

다음 예시에서 v1.0.1은 패치 릴리스입니다.

기존 버전: v1.0.0

새 버전: v1.0.1

저장소에서 모듈 코드에 태그를 달아 패치 릴리스를 게시하며, 태그의 패치 버전 번호를 올립니다. 자세한 내용은 Publishing a module을 참고하세요.

호환성을 깨지 않는 API 변경 게시하기

모듈의 공개 API에 호환성을 깨지 않는 변경을 하고, 그 변경을 마이너 버전 릴리스로 게시할 수 있어요.

이 버전은 API를 바꾸지만 호출하는 코드를 깨뜨리지는 않는 방식으로 바꿉니다. 여기에는 모듈 자신의 의존성 변경이나 새 함수·메서드·구조체 필드·타입의 추가가 포함될 수 있어요. 포함하는 변경에도 불구하고, 이런 종류의 릴리스는 모듈의 함수를 호출하는 기존 코드에 하위 호환성과 안정성을 보장합니다.

마이너 릴리스는 모듈 버전 번호의 마이너 부분을 올립니다. 자세한 내용은 Module version numbering을 참고하세요.

다음 예시에서 v1.1.0은 마이너 릴리스입니다.

기존 버전: v1.0.1

새 버전: v1.1.0

저장소에서 모듈 코드에 태그를 달아 마이너 릴리스를 게시하며, 태그의 마이너 버전 번호를 올립니다. 자세한 내용은 Publishing a module을 참고하세요.

호환성을 깨뜨리는 API 변경 게시하기

메이저 버전 릴리스를 게시해서 하위 호환성을 깨뜨리는 버전을 게시할 수 있어요.

메이저 버전 릴리스는 하위 호환성을 보장하지 않습니다. 대개 이전 버전의 모듈을 사용하는 코드를 깨뜨릴 모듈의 공개 API 변경을 포함하기 때문이에요.

메이저 버전 업그레이드가 모듈에 의존하는 코드에 미칠 수 있는 큰 방해를 고려하면, 가능하면 메이저 버전 업데이트를 피해야 합니다. 메이저 버전 업데이트에 대한 자세한 내용은 Developing a major version update를 참고하세요. 호환성을 깨뜨리는 변경을 피하는 전략은 블로그 글 Keeping your modules compatible를 보세요.

다른 종류의 버전을 게시하는 것이 본질적으로 모듈 코드에 버전 번호를 태그하는 일이라면, 메이저 버전 업데이트를 게시하는 데는 더 많은 단계가 필요합니다.

  • 새 메이저 버전 개발을 시작하기 전에, 저장소에 새 버전의 소스가 들어갈 공간을 만드세요. 한 가지 방법은 새 메이저 버전과 그 이후의 마이너·패치 버전을 전담하는 새 브랜치를 저장소에 만드는 것입니다. 자세한 내용은 Managing module source를 참고하세요.
  • 모듈의 go.mod 파일에서 모듈 경로를 수정해서 새 메이저 버전 번호를 이어 붙이세요. 예를 들면:
example.com/mymodule/v2

모듈 경로가 모듈의 식별자라는 점을 감안하면, 이 변경은 실질적으로 새 모듈을 만드는 것입니다. 패키지 경로도 바꾸므로 개발자가 실수로 자기 코드를 깨뜨리는 버전을 import 하지 않게 해줘요. 대신 업그레이드하려는 사람들은 기존 경로를 새 경로로 명시적으로 교체하게 됩니다.

  • 코드에서, 업데이트 중인 모듈의 패키지를 import 하는 모든 패키지 경로를 바꾸세요. 모듈 경로를 바꿨기 때문에 이 작업이 필요해요.
  • 다른 새 릴리스처럼, 공식 릴리스 전에 피드백과 버그 리포트를 받기 위해 사전 릴리스 버전을 게시해야 합니다.
  • 저장소에서 모듈 코드에 태그를 달아 새 메이저 버전을 게시하며, 태그의 메이저 버전 번호를 올립니다 — 예를 들어 v1.5.2에서 v2.0.0으로요.

자세한 내용은 Publishing a module을 참고하세요.

더 알아보기 (Learn more)