무엇이 바뀌었고 무엇을 해야 하는지 알 수 있게 변경 이력 쓰기

## 누가 변경 이력을 읽고 어떤 변경이 그 사람과 관계있는지 알아보기 변경 이력은 기계가 검증하는 명세나 개발 활동을 가공 없이 쏟아 놓은 자료가 아니라 소프트웨어 변경의 영향을 받는 사람을 위해 작성하세요. 모든 편집상의 선택은 독자가 더 적은 노력으로 릴리스를 이해하도록 도와야 합니다. 초안을 작성하기 전에 다음을 파악하세요. - 설명하려는 릴리스 또는 버전. - 제품, 라이브러리, 서비스 또는 문서에 의존하는 사람. - 동작, 기대, 호환성, 접근성, 보안 또는 필요한 조치를 바꾸는 변경 사항. - 프로젝트에서 이미 사용 중인 버전 관리, 제목 및 항목 작성 규칙. 규칙은 판단을 대신하는 수단이 아니라 도구로 사용하세요. 기존 구조가 독자의 릴리스 비교에 도움이 된다면 유지하되, 단지 특정 라벨에 맞추려고 변경 사항을 오해를 부르는 표현에 억지로 끼워 맞추지는 마세요. 규칙을 엄격하게 적용해야 한다면 기여자가 이를 합리적으로 적용할 수 있도록 이유를 설명하세요. 변경 이력의 원칙을 설정 지침 및 일상적인 기여 절차와 분리하세요. 각 유형의 안내마다 하나의 공식 위치를 유지하고, 시간이 지나면서 내용이 달라질 수 있는 지침을 중복해서 쓰는 대신 그 위치로 연결하세요. ## 읽는 사람과 관계있는 변경만 넣고 왜 중요한지 쓰기 후보 변경 사항을 독자의 관점에서 검토하세요. 어떤 항목이 사람이 할 수 있는 일, 관찰할 수 있는 것, 의존할 수 있는 대상, 구성하거나 마이그레이션하거나 보호할 수 있는 것을 바꾼다면 포함하세요. 의미 있는 효과가 없는 내부 활동은 제외하되, 관련된 운영상 또는 호환성상의 결과를 설명하는 경우는 예외입니다. 포함한 각 변경 사항에 대해 다음 질문에 답하세요. 1. 관찰 가능한 측면에서 무엇이 바뀌었나요? 2. 누가 어떤 조건에서 영향을 받나요? 3. 이 변경이 왜 중요한가요? 4. 독자가 조치를 취해야 하나요? 그렇다면 어떤 조치가 필요한가요? 결과부터 제시하세요. 오해를 방지하는 데 필요한 맥락만 추가하세요. 조건, 예외 및 마이그레이션에 미치는 영향을 명확히 밝히고, 모호한 요약 뒤에 숨기지 마세요. 어떤 도구가 인기 있다는 이유만으로 특정 도구를 홍보하지 말고, 입증된 커뮤니케이션 문제를 해결하지 못하는 절차를 새로 만들지도 마세요. 현재 접근 방식 때문에 독자가 중요한 변경을 이해하지 못하는 경우가 아니라면 간단한 항목과 프로젝트의 기존 작업 흐름을 우선하세요. 지침과 권고에는 그 근거가 포함되어야 합니다. 독자가 상충 관계와 의도한 이점을 알 수 있어야 충분한 정보를 바탕으로 다른 의견을 제시할 수 있습니다. ## 변경마다 영향과 해야 할 일을 쉬운 말로 쓰기 쉬운 언어를 사용하고 핵심을 먼저 제시하세요. 진입 장벽을 세우는 표현, 내부자만 아는 줄임말, 장식적인 복잡성, 독자가 핵심 주장을 다시 구성해야 하는 문장을 피하세요. 비원어민 독자가 처음 읽을 때 이해할 수 있고 번역자가 재해석하지 않고 직접 번역할 수 있는 표현을 선택하세요. 다음 요소를 명확히 구분하세요. - 변경 자체: 이전 동작과 새로운 동작에 대한 구체적인 설명. - 영향: 영향을 받는 사용자, 환경, 버전 또는 작업 흐름. - 이유: 해결한 문제 또는 지키려는 원칙. - 조치: 독자가 수행해야 하는 업그레이드, 구성, 마이그레이션 또는 검증 단계. 확실성이나 영향을 과장하지 마세요. 동작이 맥락에 따라 달라진다면 보편적인 명령을 내리는 대신 해당 조건을 명시하세요. 독자가 취해야 할 조치가 없다면 억지로 만들어 내지 마세요. 항목과 버전 전반에서 용어를 일관되게 사용하세요. 피할 수 없는 전문 용어는 처음 사용할 때 설명하고, 중요한 차이를 보존하며, 경고나 호환성을 깨는 변경에 관한 정보를 약화하는 완곡한 표현을 피하세요. 관련 문서, 기여 참고 사항 및 커밋 메시지에도 핵심을 먼저 제시하는 똑같이 명확한 방식을 적용하여, 변경 기록을 뒷받침하는 원천 정보의 일관성을 유지하세요. ## 번역이 원문과 같은 뜻인지 확인하고 마지막 결정은 사람이 하기 번역을 핵심적인 변경 커뮤니케이션으로 다루세요. 특정 버전의 번역은 존재하거나, 그 번역을 기여하는 방법에 대한 명확한 안내를 제공해야 합니다. 번역은 정확성과 표준 원문과의 일관성을 유지하면서, 해당 언어와 문화적 맥락에서도 이해하기 쉬워야 합니다. 프로그래머가 아닌 번역자도 편집할 수 있을 만큼 페이지 구조, 버전 라우팅 및 원문 마크업을 단순하게 유지하세요. 제목, 식별자, 버전 간 관계 또는 마크업 규칙을 변경하기 전에 그 변경이 유지 관리 중인 모든 언어와 버전에 어떤 영향을 미치는지 평가하세요. 다음 검토 순서를 사용하세요. 1. 번역하기 전에 표준 항목의 의미를 확정하세요. 2. 변경이 필요한 버전과 언어를 기록하세요. 3. 필요한 번역이 각각 존재하거나 명확한 기여 경로를 제공하는지 확인하세요. 4. 번역된 의미를 표준 원문과 비교하여 누락, 의미 반전, 변경된 조건 및 일관되지 않은 용어를 확인하세요. 5. 해당 언어와 문화를 아는 사람이 최종 편집 결정을 내리게 하세요. 기계가 생성한 텍스트를 번역자의 대체물로 사용하지 마세요. 자동화되거나 모델의 도움을 받는 검사는 누락된 범위와 가능한 불일치를 찾을 수 있지만, 의미, 문화적 적합성 및 최종 표현은 사람이 책임집니다. ## 반복 확인은 간단한 도구에 맡기고 판단은 사람이 하기 자동화를 사용하여 언어, 버전 및 표시 환경 전반에서 반복되는 검증을 줄이세요. 번역 범위 검사, 버전 라우팅 테스트, 의미 비교 보조 도구, 접근성 검사, 시각적 또는 기능적 회귀 테스트가 적합한 대상입니다. 한 번 만든 뒤에는 모델 없이 로컬이나 오프라인에서 실행할 수 있는 일반적이고 재사용 가능한 도구를 우선하세요. 언어 모델이 도구의 설계나 구현을 한 번 도울 수는 있지만, 그 결과로 만들어진 검사는 내용을 확인할 수 있고, 반복 가능하고, 실행 비용이 낮으며, 독립적으로 작동할 수 있어야 합니다. 모델이 해서는 안 되는 일은 다음과 같습니다. - 인간 번역자나 문화적 검토를 대신하는 일. - 프로젝트의 편집 방침이나 지침의 의미를 결정하는 일. - 독립적인 필요성이 없는 기능이나 절차를 정당화하는 일. 변경 이력 항목이 정확하고 유용하며 적절한지는 사람이 결정합니다. 도구는 증거를 제공할 뿐, 결론을 소유하지 않습니다. 게시 시스템을 단순하고 오래 유지되도록 만드세요. 기존 빌드 및 저작 도구 체인을 우선하고, 현재 접근 방식으로 구체적인 요구 사항을 안전하게 충족할 수 없을 때만 종속 항목, 서비스, 데이터베이스 또는 새로운 런타임을 추가하세요. 개발 전용 검증 도구가 불필요한 프로덕션 요구 사항이 되어서는 안 됩니다. 게시하기 전에 표준 항목이 명확하고, 필요한 버전과 번역이 모두 포함되어 있으며, 자동화 검사가 실제 결과를 냈고, 사람이 최종 의미를 검토했는지 확인하세요.