안녕하세요. 생활코딩에 글을 올리는 것은 처음입니다.

https://semver.org/lang/ko/ 를 정리해서 프레젠테이션으로 만들어 봤습니다.

다만 약간 글자가 많아 번잡해 보입니다. 만드는데는 한 3시간 반정도 걸린듯 합니다. 많이 사용해주시면 감사드리겠습니다.

깃허브를 통해 배포하고 있습니다. 또한 MIT 라이센스로 배포되지만 일부 제약 사항에 대해서는 맨 마지막 장을 참고하여주시기 바랍니다.

아래 링크를 누르시면 바로 다운로드됩니다. PPT와 PDF 두 종류로 모두 제공합니다.
https://github.com/Shin-Jae…/…/raw/master/develop/유의적버전.pptx

https://github.com/Shin-JaeH…/…/raw/master/develop/유의적버전.pdf


유의적 버전

신재헌(Shin-JaeHeon)

20180902일 제작됨, v1.0.0

https://github.com/Shin-JaeHeon/ppt/blob/master/develop/유의적버전.pptx 

CC BY 3.0으로 배포되는 https://semver.org/lang/ko/의 내용을 참고 했습니다


  2. 목차

  • 유의적 버전이란?
  • 왜 유의적 버전을 사용해야 하나요?
  • 유의적 버전을 쓰는 방법
  • 우선순위
  • 이래서 유의적 버전을 사용하고 있습니다.
  • FAQ
  • 작성자 및 라이선스 안내

3. 유의적 버전이란?

버전을 통해 API의 변경을 표현하는 명세입니다

버전은 X.Y.Z (주.부.수)로 표현합니다

4. 왜 유의적 버전을 사용해야 하나요?

나날이 소프트웨어의 의존성은 증가하고 있습니다

어느 버전까지 호환되는지를 알아보는 것은 비용이 많이 듭니다

매번 Readme.md를 읽어볼 수는 없습니다

기존의 소프트웨어와 테스트를 하는 것은 귀찮고 힘들고 시간과 비용이 많이 듭니다

편하게 의존성 관리를 하고 싶으면 유의적 버전을 사용해야합니다

5. 왜 유의적 버전을 사용해야 하나요?

  명시적인 정의와 규칙이 존재합니다

앞으로도 계속해서 같은 규칙으로 버전을 작성할 것입니다

사용자에게 개발자의 의도를 쉽게 표현할 수 있습니다

시간과 비용을 절약할 수 있습니다

6. 유의적 버전을 쓰는 방법

버전은 숫자로 합니다

식별자는 한 글자 이상으로 합니다

숫자는 절대로 앞에 0을 붙이지 않습니다

  • O 1.2.3
  • X 1.2.03

표현은 X.Y.Z (주.부.수)

1.0.0은 공개 API를 정의합니다

7. 유의적 버전을 쓰는 방법

기존 버전과 호환되지 않으면 주 버전을 올립니다.

 기존 버전과 호환되면서 기능이 추가되면 부 버전을 올립니다

기존 버전과 호환되면서 버그를 수정한 것이면 수 버전을 올립니다

모든 버전은 증가합니다

8. 유의적 버전을 쓰는 방법

공개 API에 기존과 호환되는 새로운 기능을 추가하는 경우

반드시 부(x.Y.z | x > 0)버전을 올립니다

공개 API의 일부를 앞으로 제거(deprecate)할 경우에도 수 버전을 올립니다

부 버전이 올라가면 수 버전은 0부터 다시 시작합니다

수 버전(x.y.z | x > 0)은 반드시 기존과 호환되는 버그 수정의 경우

버그 수정은 잘못된 내부 기능을 고치는 것으로 정의합니다

9. 유의적 버전을 쓰는 방법

주 버전의 변경은 부 버전이나 수 버전급 변화를 포함할 수 있습니다

부 버전과 수 버전을 0으로 초기화합니다

특정 버전을 배포 후에는 절대로 내용을 변경할 수 없습니다

변경점이 생기면 반드시 새로운 버전으로 배포해야 합니다

주 버전 0(0.y.z)은 초기 개발을 위해 사용합니다

이 버전은 안정적이지 않은 편으로 보는 것이 좋습니다

10. 유의적 버전을 쓰는 방법

정식 배포를 앞둔(pre-release) 버전의 표기 방법

수 버전 뒤에 붙임표(-)를 붙이고 마침표(.)로 구분된 식별자를 사용할 수 있습니다

식별자는 아스키 문자, 숫자(앞에 0을 붙이지 않습니다), 붙임표로 하고 한 글자 이상으로 합니다

  •   [0-9A-Za-z-]

예시

  • 1.0.0-alpha
  • 1.0.0-alpha.1
  • 1.0.0-0.3.7
  • 1.0.0-x.7.z.92

정식 배포 전 버전은 보통 버전보다 우선순위가 낮습니다

정식 배포 전 버전은 아직 불안정할 수 있습니다

연관된 일반 버전에 대한 호환성 요구 사항이 충족되지 않을 수 있습니다

11. 유의적 버전을 쓰는 방법

빌드 메타데이터의 표기 방법

수 버전이나 정식 배포 전 식별자 뒤에 표현할 수 있습니다.

더하기(+) 기호를 사용합니다

식별자는 아스키 문자, 숫자, 붙임표로 하고 한 글자 이상으로 합니다

  •   [0-9A-Za-z-]

빌드 메타 데이터는 버전 간의 우선순위를 판단하는데 사용하지 않습니다

빌드 메타 데이터만 다른 두 버전의 우선순위는 같습니다

예시

  • 1.0.0-alpha+001
  • 1.0.0+20130313144700
  • 1.0.0-beta+exp.sha.5114f85

12. 우선순위

우선순위의 계산 방법

주, 부, 수 버전, 정식 배포 전 버전의 식별자를 나누어 계산합니다

빌드 메타 데이터는 우선순위에 영향을 주지 않습니다

차이가 나는 부분이 나타나면 결정됩니다

주, 부, 수는 숫자로 비교합니다

  • 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1

13. 우선순위

주, 부, 수 버전이 같은 경우 정식 배포 전 버전이 표기된 경우가 더 낮습니다

반드시 마침표로 구분된 식별자를 차례대로 비교하면서 차이점을 찾습니다

숫자로만 구성된 식별자는 수의 크기로 비교합니다

알파벳이나 붙임표가 포함되면 아스키 문자열 정렬을 합니다

숫자로만 구성된 식별자는 어떤 경우에도 문자와 붙임표가 있는 식별자보다 낮습니다

앞선 식별자가 모두 같은 배포 전 버전의 경우에는 필드 수가 많은 쪽이 더 높습니다

예시

  • 1.0.0-alpha < 1.0.0-alpha.1
  • 1.0.0-alpha.1 < 1.0.0-alpha.beta
  • 1.0.0-alpha.beta < 1.0.0-beta
  • 1.0.0-beta < 1.0.0-beta.2
  • 1.0.0-beta.2 < 1.0.0-beta.11
  • 1.0.0-beta.11 < 1.0.0-rc.1
  • 1.0.0-rc.1 < 1.0.0

14. 이래서 유의적 버전을 사용하고 있습니다

Car이라는 라이브러리가 있다고 예를 들면,

이 라이브러리는 유의적 버전이 적용된 Engine이라는 라이브러리에 의존합니다

Car라는 라이브러리를 만들었을 때 Engine은 3.1.0 이었다면,

Car는 Engine이 3.1.0일 때 처음으로 추가된 기능을 사용했습니다

그러므로 Engine의 의존성으로 3.1.0 이상, 4.0.0 미만으로 지정할 수 있습니다

이제 Engine의 3.1.1 버전과 3.2.0 버전이 공개되었다면,

패키지 관리 시스템에 그 버전을 넣을 수 있습니다.

또한 기존의 소프트웨어와 호환될 것이라고 알 수 있습니다.

15. FAQ

초기 개발 단계에 0.y.z 버전 관리 방법은 무엇인가요?

가장 간단한 방법은 최초 개발 배포를 0.1.0으로 합니다

그리고 이후 배포마다 부버전을 올리는 것입니다

언제 1.0.0을 배포해야 할지 어떻게 알 수 있나요?

 소프트웨어가 실 서비스에 쓰이기 시작했다면 1.0.0이라 여길 수 있습니다

사용자들이 믿고 쓸 수 있는 안정한 API가 있으면 1.0.0일 것입니다

하위 버전 호환성에 대해 우려하기 시작했다면 이미 1.0.0일 수 있습니다

16. FAQ

유의적 버전 짓기가 빠른 개발을 방해하지 않을까요?

주 버전 0이 신속한 개발을 위한 것입니다

만약 API를 매일같이 바꾸고 있다면 0.y.z 버전을 쓰거나

별도의 다음 번 주 버전 배포를 앞둔 개발 브랜치를 사용해야 합니다

17. FAQ

주 버전을 사소한 이유로 매번 올리면 금새 버전이 42.0.0이 되어버리지 않나요?

의존하는 코드가 많은 소프트웨어에, 호환되지 않는 변화를 가볍게 도입해서는 안됩니다

주 버전을 업그레이드하는데 필요한 비용이 어마어마해질 수 있습니다

바뀌는 부분에 인한 여파와 그 비용과 혜택을 충분히 평가해야 합니다

18. FAQ

공개 API 전체를 문서로 만드는 것은 일이 너무 많지 않나요?

다른 사람들이 쓰라고 만든 것을 적절히 문서로 만드는 것은 책임입니다

효율적인 프로젝트를 유지하기 위해 복잡성을 관리하는 일 중요한 일입니다

유의적 버전을 사용하고 잘 정의한 공개 API가 편리합니다

19. FAQ

부버전을 올렸는데, 실수로 호환되지 않는 변경이 들어갔습니다.

유의적 버전 명세를 어겼다는 사실을 알게 되면, 즉시 문제를 해결하도록 합니다

호환성이 깨진 부분을 복구해서 새 부버전을 배포합니다

이 경우라도 이미 배포된 버전을 변경해서는 안됩니다

필요한 경우라면 문제가 되는 버전을 문서로 표시하여 이용자로 하여금 주의하도록 합니다

20. FAQ

공개 API는 유지한 채 내부의 의존성 변경은 가능한가요?

  공개 API에 영향을 주지 않으므로 호환된다고 여깁니다

변화가 수 버전 수준인지 부 버전 수준인지 결정하는 것은

버그를 수정하고자 한 작업인지

새로운 기능을 추가하기 위해서인지

후자의 경우, 추가적인 코드를 예상할 것입니다

그렇다면 부 버전의 증가는 당연합니다

21. FAQ

실수로 버전 증가와 맞지 않게 공개 API 변경을 했습니다

수 버전 배포에서 잘못된 코드가 들어가서 깨지게 된 경우에

공개 API가 원래 의도했던 대로 사용될 수 있게 바꾸는 작업에 영향받는 사람이 많다면

수정사항이 엄밀히 따지면 수 버전 배포로 여겨져야 한다 하더라도

주 버전 배포를 하는 것이 최선일 것입니다

유의적 버전은 어떻게 버전이 바뀌는지 의미를 전달하는 것이 전부입니다

변경이 사용자에게 중요한 의미가 있다면, 버전 번호로 잘 알릴 수 있도록 합니다

22. FAQ

제거하는 기능에 대해서는 어떻게 할까요?

문서를 업데이트해서 사용자들에게 변화를 알립니다.

해당 기능이 제거될 거라 표시된 새 부 버전을 적절한 시기에 배포합니다

새 주 버전에서 완전히 기능을 제거하기 전에 제거될 것이라 표시한 부 버전 배포를 진행합니다

사용자들이 원활하게 새로운 API를 사용할 수 있도록 해야 합니다

23. FAQ

유의적 버전의 문자열 길이 제한이 있습니까?

  없더라도 255자의 버전 문자열은 지나치게 긴 것임이 틀림없습니다

간결할 수록 버전을 읽기가 편리합니다

24. 작성자 및 라이선스 안내

유의적 버전 명세는

그라바타(Gravatars)의 창시자이자 깃허브(GitHub)의 공동창업자인

톰 프레스턴-베르너(Tom Preston-Werner)가 작성했습니다.

  유의적 버전의 한국어 번역은

김대현(http://hatemogi.com/)님이 했습니다

번역과 관련된 의견은 한국어판 유의적 버전 깃허브 프로젝트에 이슈를 남겨주세요

이 프레젠테이션은

신재헌(https://github.com/Shin-JaeHeon)이 제작했습니다

관련된 의견은 깃허브에 이슈를 남겨주세요

MIT 라이선스로 배포되지만 반드시 아래의 내용이 포함되어야 합니다.

  •   https://github.com/Shin-JaeHeon/ppt/blob/master/develop/유의적버전.pptx
  •   CC BY 3.0으로 배포되는 https://semver.org/lang/ko/의 내용을 참고했습니다.
  •   제작자 : 신재헌(Shin-JaeHeon) (한/영 표기가 필수입니다)


'Programming' 카테고리의 다른 글

유의적버전에 대해 정리한 프레젠테이션을 배포합니다.  (0) 2018.09.03
robots.txt  (0) 2017.08.15
SHA란?  (0) 2017.08.15

+ Recent posts

티스토리 툴바