Add translation for 1.1.0 (#610)
This commit is contained in:
Jaewon-Yun
GitHub
parent
d1bdf1fa6a
commit
4e50ba2b63
|
|
@ -0,0 +1,290 @@
|
|||
---
|
||||
title: Keep a Changelog
|
||||
description: 동료들이 git 로그를 그대로 changelogs에 올리게 내버려 두지 마세요.
|
||||
language: ko
|
||||
version: 1.1.0
|
||||
---
|
||||
.header
|
||||
.title
|
||||
%h1= current_page.data.title
|
||||
%h2= current_page.data.description
|
||||
|
||||
= link_to data.links.changelog do
|
||||
Version
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog{ lang: "en" }= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Changelog는 무엇인가요?
|
||||
|
||||
%p
|
||||
Changelog는 프로젝트의 각 버전에 대해 주목할 만한 변경 사항들을 시간 순서대로 정리한 파일입니다.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
왜 changelog를 유지해야 하나요?
|
||||
|
||||
%p
|
||||
사용자와 기여자가 프로젝트의 각 릴리즈(또는 버전)간에 정확히 어떤 주목할만한 변경 사항이 있는지 알기 쉬워집니다.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
누가 changelog를 필요로 하나요?
|
||||
|
||||
%p
|
||||
사람들이 필요로 합니다. 개발자이든 사용자이든, 소프트웨어의 최종 사용자는 소프트웨어에 무엇이 있는지 관심이 있는 사람입니다.
|
||||
소프트웨어에 변경 사항이 있을 때, 사람들은 왜 그리고 어떻게 바뀌었는지 알고 싶어 합니다.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
어떻게 좋은 changelog를 만들수 있나요?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
가이드 원칙
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogs는 <em>사람을 위한 것입니다.</em> 기계를 위한 것이 아닙니다.
|
||||
%li
|
||||
모든 단일 버전에 대한 항목이 있어야 합니다.
|
||||
%li
|
||||
같은 유형의 변경 사항은 그룹으로 묶어야 합니다.
|
||||
%li
|
||||
버전 및 섹션들은 링크를 통해 연결될 수 있어야 합니다.
|
||||
%li
|
||||
최신 버전이 처음에 와야 합니다.
|
||||
%li
|
||||
각 버전의 릴리즈 날짜를 표시해야 합니다.
|
||||
%li
|
||||
프로젝트가 #{link_to "시맨틱 버저닝", data.links.semver}을 따르는지를 언급해야 합니다.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types 변경 유형
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
새로운 기능
|
||||
%li
|
||||
%code Changed
|
||||
기존 기능의 변경
|
||||
%li
|
||||
%code Deprecated
|
||||
곧 없어질 기능
|
||||
%li
|
||||
%code Removed
|
||||
없어진 기능
|
||||
%li
|
||||
%code Fixed
|
||||
버그 수정
|
||||
%li
|
||||
%code Security
|
||||
보안 취약점에 관하여
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Changelog를 관리하기 위해 필요한 노력을 어떻게 줄일 수 있나요?
|
||||
|
||||
%p
|
||||
<code>Unreleased</code> 섹션을 가장 위에 두어 다가올 변경 사항들을 추적할 수 있도록 하세요.
|
||||
|
||||
%p 이것은 두 가지 목적이 있습니다.
|
||||
|
||||
%ul
|
||||
%li
|
||||
사람들이 향후 릴리즈에서 예상되는 변경 사항들을 확인할 수 있습니다.
|
||||
%li
|
||||
릴리즈 시점에 <code>Unreleased</code> 섹션의 변경 사항들을 새 릴리즈 버전의 섹션으로 이동할 수 있습니다.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Changelogs가 나빠질 수 있나요?
|
||||
|
||||
%p 네. 여기에 changelog가 쓸모없게 되는 몇 가지 경우들이 있습니다.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
커밋 로그 차이(Commit log diffs)
|
||||
|
||||
%p
|
||||
커밋 로그의 차이를 changelog로 사용하는 것은 안 좋은 생각입니다.
|
||||
커밋 로그는 머지 커밋, 모호한 타이틀을 가진 커밋, 문서 변경 등 노이즈로 가득 차 있습니다.
|
||||
|
||||
%p
|
||||
커밋의 목적은 소스 코드 진화의 단계를 기록하기 위함입니다.
|
||||
어떤 프로젝트는 커밋을 정리하지만, 어떤 프로젝트는 하지 않습니다.
|
||||
|
||||
%p
|
||||
changelog 기재의 목적은 흔히 다수의 커밋에 걸친 주목할만한 차이를
|
||||
최종 사용자에게 명확하게 전달하기 위해 문서화하는 것입니다.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
없어질 기능들(Deprecations) 무시하기
|
||||
|
||||
%p
|
||||
사람들이 다른 버전으로 업데이트 할 때, 언제 어떤 것이 중단될지(break) 극도로 분명해야 합니다.
|
||||
앞으로 없어질 기능들(deprecations)이 나열된 버전으로 업데이트하고,
|
||||
더 이상 사용하지 않는 기능(deprecated)을 제거한 뒤, 그 기능들이
|
||||
정말 삭제된 버전으로 업데이트 하는 것이 가능해야 합니다.
|
||||
|
||||
%p
|
||||
최소한, 앞으로 없어질 기능들, 제거된 것 그리고 모든 급격한 변화(breaking changes)는 changelog에 남기십시오.
|
||||
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
혼란스러운 날짜
|
||||
|
||||
%p
|
||||
지역별 날짜 포맷은 전세계에 걸쳐 다양하며 모든 사람이 직관적으로 느낄 수 있는 인간 친화적 날짜 포맷을 찾기 힘든 경우가 많습니다.
|
||||
<code>2017-07-17</code> 같은 날짜 포맷(연, 월, 일)의 장점은
|
||||
큰 단위부터 작은 단위의 순서를 따른다는 것입니다.
|
||||
월과 일의 위치가 뒤바뀐 어떤 포맷과 다르게, 이 포맷은 다른 날짜 포맷과 모호하게 겹치는 부분이 없습니다.
|
||||
이런 이유와 이 포맷이 #{link_to "ISO standard", data.links.isodate}라는 사실이
|
||||
changelog 기재에 이 날짜 포맷을 추천하는 이유입니다.
|
||||
|
||||
%h4#inconsistent-changes
|
||||
%a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
|
||||
일관성 없는 변경 사항
|
||||
|
||||
%p
|
||||
일부 변경 사항만 언급하는 changelog는 changelog가 없는 것만큼 위험할 수 있습니다.
|
||||
물론 기록하지 않아도 되는 변경 사항도 많이 있습니다.
|
||||
예를 들어, 단순히 공백 하나를 삭제한 것은 어떤 경우에도 기록할 필요가 없을 수도 있습니다.
|
||||
하지만 중요한 변경 사항은 changelog에 명시되어야 합니다.
|
||||
일관성 없이 변경 사항을 적용하면 사용자들이 changelog가 단일 진실 공급원(Single source of truth)이라고
|
||||
착각할 수 있습니다.
|
||||
큰 권한에는 큰 책임이 따릅니다. 좋은 변경 로그는 일관성 있게 업데이트되는 변경 로그를 의미합니다.
|
||||
|
||||
%aside
|
||||
안티패턴은 더 있습니다.
|
||||
= link_to "이슈 오픈하기", data.links.issue
|
||||
나 pull request를 통해
|
||||
안티패턴들을 모으는 것을 도와주세요.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
자주 하는 질문
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Changelog의 표준 포맷이 있나요?
|
||||
|
||||
%p
|
||||
없습니다. #{link_to "GNU changelog 스타일 가이드", data.links.gnustyle} 또는
|
||||
두 문단 정도의 #{link_to "GNU NEWS file", data.links.gnunews} "가이드라인"이 있습니다.
|
||||
하지만 둘 다 부적절하거나 불충분합니다.
|
||||
|
||||
%p
|
||||
이 프로젝트의 목표는
|
||||
= link_to "더 나은 changelog 규칙", data.links.changelog
|
||||
입니다.
|
||||
이것은 오픈소스 커뮤니티에서 좋은 사례를 관찰하고 모으는 데서 비롯됩니다.
|
||||
|
||||
%p
|
||||
건강한 비판, 토론 및 개선 제안은
|
||||
= link_to "환영합니다.", data.links.issue
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
Changelog 파일의 이름을 무엇으로 지어야 하나요?
|
||||
|
||||
%p
|
||||
<code>CHANGELOG.md</code>라고 만드세요. 어떤 프로젝트는
|
||||
<code>HISTORY</code>, <code>NEWS</code> 또는 <code>RELEASES</code>를 사용합니다.
|
||||
|
||||
%p
|
||||
changelog 파일의 이름이 무슨 상관이냐고 생각하기 쉽겠지만,
|
||||
최종 사용자가 주목할 만한 변경 사항을 일관적으로 찾기 쉬워집니다.
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
깃허브 릴리즈는 어떻게 하나요?
|
||||
|
||||
%p
|
||||
이것은 훌륭한 계획입니다. #{link_to "릴리즈", data.links.github_releases}는
|
||||
직접 릴리즈 노트를 추가하여 간단한 깃 태그(예를 들어 <code>v1.0.0</code> 태그)를
|
||||
풍부한 릴리즈 노트로 전환하거나, 주석이 달린 깃 태그 메시지를 가져와서
|
||||
릴리즈 노트로 전환할 수 있습니다.
|
||||
|
||||
%p
|
||||
깃허브 릴리즈는 이식 불가능한 changelog를 생성하며, 이는 깃허브 내에서만 사용자들에게 보여집니다.
|
||||
Keep a Changelog 포맷처럼 보이게 만드는 게 가능하지만, 좀 더 복잡해지는 경향이 있습니다.
|
||||
|
||||
%p
|
||||
일반적인 대문자 파일들(<code>README</code>, <code>CONTRIBUTING</code> 등)과 달리,
|
||||
깃허브 릴리즈의 현재 버전은 최종 사용자가 쉽게 찾아볼 수 없습니다.
|
||||
또 다른 사소한 이슈는 깃허브 릴리즈의 인터페이스가 현재 각 릴리스 간의 커밋 로그 링크를 제공하지 않는다는 것입니다.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Changelog를 자동으로 파싱할 수 있나요?
|
||||
|
||||
%p
|
||||
사람들이 매우 다양한 포맷과 파일 이름을 따르기 때문에 어렵습니다.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", data.links.vandamme}은 Gemnasium 팀에 의해
|
||||
생성된 Ruby gem이고 전부는 아니지만 많은 오픈소스 프로젝트의 changelog를 파싱합니다.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
삭제된 릴리즈(Yanked release)는 어떻게 하나요?
|
||||
|
||||
%p
|
||||
삭제된(Yanked) 릴리즈는 심각한 버그나 보안 이슈 때문에 소스에서 들어내 버린 버전을 말합니다.
|
||||
이런 버전은 changelog에 나타내지 않는 경우가 않지만, 나타내야 합니다. 이것이 삭제된 릴리즈를
|
||||
표시하는 방법입니다.
|
||||
|
||||
%p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
사람들이 알아차리는 것이 중요하기 때문에 눈에 띄는 <code>[YANKED]</code> 태그가 있습니다.
|
||||
대괄호 안에 있기 때문에 프로그래밍적으로 파싱하기에도 용이합니다.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Changelog를 다시 작성한 적이 있나요?
|
||||
|
||||
%p
|
||||
물론입니다. changelog를 개선할 좋은 이유는 항상 있습니다.
|
||||
저는 정기적으로 changelog가 관리되지 않은 오픈소스에 pull request를 열어서
|
||||
누락된 릴리즈를 추가합니다.
|
||||
|
||||
%p
|
||||
또한, 어떤 버전의 급격한 변화에 대한 언급을 잊은 걸 발견할 수도 있습니다.
|
||||
이 경우엔 changelog를 업데이트하는 것이 당연히 중요합니다.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
어떻게 기여할 수 있나요?
|
||||
|
||||
%p
|
||||
이 문서가 <strong>진리</strong>는 아닙니다. 이것은 제가 모은 정보와 예제들과 함께
|
||||
신중하게 고려한 의견입니다.
|
||||
|
||||
%p
|
||||
이는 우리 커뮤니티가 합의점에 도달하기를 원하기 때문입니다. 저는 최종결과 못지않게 토론도 중요하다고 생각합니다.
|
||||
|
||||
%p
|
||||
그러니 많은 <strong>#{link_to "참여", data.links.repo}</strong> 부탁드립니다.
|
||||
|
||||
.press
|
||||
%h3 담화
|
||||
%p
|
||||
왜 관리자와 기여자가 changelog를 신경써야하는지, 또한 이 프로젝트의 동기에 대해 이야기하기 위해
|
||||
#{link_to "The Changelog 팟캐스트", data.links.thechangelog}에 다녀왔습니다.
|
||||
Loading…
Reference in New Issue