Introduction
•
Release note 생성, versioning 자동화를 위한 규격를 기반으로 release note 생성, versioning을 통합 처리하는 Semantic Release에 관한 논의이다. Motivation
다음의 요구사항을 만족하는 도구의 필요성 발생.
•
해당 도구는 commit release note 생성, versioning을 자동화해야 한다.
•
•
해당 도구는 특정 git repository(e.g. GitHub) 또는 특정 CI/CD 도구(e.g. GitHub Actions)에 대한 의존성이 없어야 한다.
•
해당 도구는 특정 git repository에 대한 의존성은 없더라도 연동은 가능해야 한다.
◦
e.g. #1. release note에 기입된 commit message에 대한 git repo로의 link 제공
◦
e.g. #2. release note에 기입된 version과 이전 버전과의 diff report 또는 diff repot link 제공
Semantic Release 개요
•
github link : (Star 18.3k, Fork 1.7k. 23.07.24 현재)
•
위 site에서의 Semantic Release 소개
시맨틱 릴리즈는 다음 버전 번호 결정, 릴리즈 노트 생성, 패키지 게시를 포함한 전체 패키지 릴리즈 워크플로우를 자동화합니다.
이는 사람의 감정과 버전 번호 사이의 즉각적인 연관성을 제거하고, 시맨틱 버전 관리 사양을 엄격하게 준수하며, 변경사항의 영향을 소비자에게 전달합니다.
관련 RELEASE 관리 도구와 Semantic Release와의 관계
RELEASE 관리 도구로서 Semantic Release가 타 도구에 비해 현 목적에 최적이라는 뜻.
•
conventional-changelog : Semantic Release를 포함한 여러 release 관련 project에서 사용하는 주요 관련 library 및 관련 eco system. 해당 github site에서 CI/CD용 release 관리 도구로 Semantic Release를 추천.•
standard-version : Semantic Release와 유사 역할의 conventional-changelog에 대한 high level package. 그간 가장 많이 사용되었으나, 현재 deprecated되어 해당 github site에서 아래의 release-please를 사용하라고 명시.•
release-please (Star : 2.8k) : deprecated된 standard-version 을 공식적으로 잇는 RELEASE 관리 도구. Semantic Release와 유사 역할이나 GitHub 환경에 (상당히) 특화됨.이외에 conventional-changelog의 eco system으로 Conventional Commits 강제화 : commitlint + pre-commit 에서 논한 commitlint , Conventional Commits 가이드 도구인 commitizen 등이 있음.
Conventional Commits 강제화 : commitlint + pre-commit 에서 논한 commitlint , Conventional Commits 가이드 도구인 commitizen 등이 있음.Semantic Release features
참고
•
Semantic Release는 Conventional Commits 이외의 타 commit message 규격도 지원하나, 여기서는 Release note 생성, versioning 자동화를 위한 규격을 기반으로 함.
Release note 생성, versioning 자동화를 위한 규격을 기반으로 함.•
Semantic Release는 npm publish 등 더 많은 기능이 있으나, Motivation에서 논의한 요구사항에 따라 이는 생략함
실행 단계별 features
%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart TB
START([시작 : npx release]) --> ANALYZE
ANALYZE[commit 분석] --> CREATE_VERSION
CREATE_VERSION[version 생성] --> CREATE_NOTE
CREATE_NOTE[CHANGELOG.md 생성 및 commit] --> TAGGING
TAGGING[생성된 commit에 버전 tagging] --> PUSH
PUSH[생성된 commit 및 버전 tag의 git push] --> COMPLETE([완료])Mermaid
복사
1.
commit 분석 : 사전 준비 단계
•
현 branch의 main 여부 확인
•
최신 버전의 commit 자동 식별 : 최신 버전 이후의 commits 만을 분석
•
참고 : Conventional Commits에 맞지 않는 commit은 drop
2.
version 생성 : commit 분석을 통해 생성될 version 추출
3.
CHANGELOG.md 생성 및 commit : 분석된 commits으로 release note 생성 및 commit
4.
생성된 commit에 버전 tagging : git tag 기반의 버전 관리
5.
생성된 commit 및 버전 tag의 git push : remote git repository에 해당 사항 반영
설치 방법
1.
node.js 설치 for Semantic Release 실행
•
node.js는 단순히 Semantic Release 실행을 위한 runtime으로, python, golang 등의 타 언어 환경에서도 동작 가능
•
되도록이면 최신 버전으로 설치. download url : https://nodejs.org/en/download
2.
아래에서 설명할 package.json 을 적용 대상 project root에 복사
•
해당 package.json에는 Semantic Release 뿐 아니라 주요 plugin에 대한 설치 정보가 함께 함
3.
해당 project에서 npm install 을 실행하여 설치
4.
설치까지 완료된 project 상태의 git 브랜치를 main 브랜치로 병합
•
Semantic Release 는 main 브랜치(또는 package.json에서 지정한 브랜치)에서만 동작함
실행 및 정상 실행 확인 방법
1.
상기 설치 방법을 통해 Semantic Release 가 설치된 main 브랜치로 checkout
2.
해당 project root에서 npx semantic-release 실행
3.
아래와 유사한 로그로 실행이 완료되는 것을 확인
[4:34:18 PM] [semantic-release] › ℹ Running semantic-release version 21.0.7
[4:34:18 PM] [semantic-release] › ✔ Loaded plugin "verifyConditions" from "@semantic-release/changelog"
...
[4:34:24 PM] [semantic-release] › ✔ Completed step "prepare" of plugin "@semantic-release/git"
[4:34:24 PM] [semantic-release] › ℹ Start step "generateNotes" of plugin "@semantic-release/release-notes-generator"
[4:34:24 PM] [semantic-release] › ✔ Completed step "generateNotes" of plugin "@semantic-release/release-notes-generator"
[4:34:25 PM] [semantic-release] › ✔ Created tag 0.10.1
[4:34:25 PM] [semantic-release] › ✔ Published release 0.10.1 on default channel
Bash
복사
•
CHANGELOG.md 가 root에 생성되었는지 확인
•
main 브랜치에 CHANGELOG.md 가 포함된 commit이 생성되었는지 확인
•
해당 commit에 신규 버전의 git tag가 생성되었는지 확인
•
해당 commit이 remote git repository에 push되었는지 확인
package.json 예제 및 예제 내 세부 항목 설명
참고
•
설정 예제를 통해 요구사항을 Semantic Release가 어떻게, 어떤 도구를 통해 만족시키는지를 설명함
•
package.json 은 JSON 형식이나 논의 편의 및 가독성 측면을 고려하여 YAML으로 변환하여 항목 별 주석으로 설명함
name: public-apigw
release: # Semantic Release 전용 section
debug: true # debug 메시지 출력
ci: false # false로 설정해야 CHANGELOG.md 생성됨
dryRun: false # (연습용이 아닌) 실제 동작용
tagFormat: "${version}" # version은 에약어. version 형식을 지정. ${version} 앞에 v 등을 붙여 v1.0.0 형식으로도 사용 가능
repositoryUrl: http://mod.lge.com/code/scm/tcn/public-apigw.git # 해당 project의 git repo URL
branches:
- main # Semantic Release 동작 대상 branch 지정
plugins:
- - "@semantic-release/commit-analyzer"
- preset: conventionalcommits # commit 메시지 분석 시 commit message 규칙 지정 to Conventional Commits
- - "@semantic-release/release-notes-generator"
- preset: conventionalcommits # release note 생성 시 commit message 규칙 지정 to Conventional Commits
writerOpts:
commitsSort: # release note 항목 생성 시 순서 지정
- subject
- scope
presetConfig:
# remote git repo 상의 commit link 포맷 지정
commitUrlFormat: http://mod.lge.com/code/projects/TCN/repos/public-apigw/commits/{{hash}}
# remote git repo 상의 이전 버전과의 비교 link 포맷 지정
compareUrlFormat: http://mod.lge.com/code/projects/TCN/repos/public-apigw/compare/diff?targetBranch=refs%2Ftags%2F{{previousTag}}&sourceBranch=refs%2Ftags%2F{{currentTag}}
types: # Conventional Commits의 commit type에 대한 표시 방법, 여부 지정
- type: feat
section: Features
- type: fix
section: Bug Fixes
- type: refactor
section: Refactors # refactor 타입은 Refectors 섹션으로 표시함을 의미
hidden: false로 # 표시 여부 지정(false는 표시함을 의미)
- type: chore
section: Etc.
hidden: false
- - "@semantic-release/changelog" # release note의 상세 항목(파일명, 타이틀 등) 지정
- changelogFile: CHANGELOG.md
changelogTitle: "# Release note : TCN public API Gateway"
- - "@semantic-release/git" # 신규 main commit 생성 시 포함될 파일 및 commit message 지정
- assets:
- CHANGELOG.md
message: "chore(release): release ${nextRelease.version} \\n\\n${nextRelease.notes}"
devDependencies: # 상기 동작을 위한 항목별 plugins
"@commitlint/cli": "^17.6.6"
"@commitlint/config-conventional": "^17.6.6"
"@semantic-release/changelog": "^6.0.3"
"@semantic-release/commit-analyzer": "^10.0.1"
"@semantic-release/git": "^10.0.1"
conventional-changelog-conventionalcommits: "^6.1.0"
conventional-commits-parser: "^4.0.0"
semantic-release: "^21.0.7"
script
YAML
복사