범위가 지정되지 않은 공개 패키지에 대한 의미 체계 릴리스를 구현하는 방법

GitHub Actions의 기능을 활용하는 의미론적 릴리스를 사용하여 범위가 지정되지 않은 공개 패키지를 게시하는 방법에 대한 자세한 지침

진화하는 소프트웨어 개발 환경에서는 버전 일관성을 유지하고 릴리스 프로세스를 자동화하는 것이 그 어느 때보다 중요합니다. 입력하다 의미론적 릴리스 : 명확하고 구조화된 버전 관리를 보장하도록 설계된 도구입니다. 범위가 지정되지 않은 공개 패키지를 활용하는 개발자의 경우 프로세스가 어려워 보일 수 있습니다. 그러나 GitHub 작업의 강력한 기능을 통해 손쉽게 자동화할 수 있습니다.

이 문서에서는 범위가 지정되지 않은 공개 패키지를 사용하는 사용자를 위해 특별히 맞춤화된 Semantic Release를 워크플로에 원활하게 통합하기 위한 단계별 지침을 제공하는 상세하고 포괄적인 가이드를 제공합니다. 소프트웨어 릴리스에 대한 간소화된 접근 방식을 살펴보고 알아보세요.

내가 만들 때 공개 패키지 , NPM에 원활하게 게시하는 데 장애물이 발생했습니다. 올바른 구성을 보장하는 것이 어려운 일이었습니다.

성공하려면 공개 패키지를 적절하게 게시하기 위한 단계별 경험을 살펴보겠습니다. NPM .

콘텐츠 개요

• 패키지 이름 지정
• 패키지 만들기
• 패키지 소스
• 토큰
• GitHub 액션 설정
• 의미론적 릴리스
• 커밋 형식
• 게시된 패키지
• 결론

패키지 이름 지정

패키지 구현을 시작하기 전에 적절한 이름을 찾는 것이 좋습니다. 이름이 이미 사용되지 않았는지 확인하려면 my_package_name 확인하고 패키지에 해당 이름을 가져오십시오. 저는 "토키"를 선택했어요. 그 시점부터는 패키지 이름을 예약하는 것이 불가능합니다. npm의 이름은 패키지를 게시해야 합니다.

패키지 만들기

목표는 콘텐츠를 콘솔에 출력하는 간단한 패키지를 개발하는 것입니다. 우리는 그것을 설치하고 실행할 수 있는지 확인해야 합니다. 빌드 프로세스에서는 간단한 방법을 사용하겠습니다. 에스빌드 .

이 기사에서는 tokky 패키지 이름을 사용하겠습니다. 초기 데이터로 package.json 생성해 보겠습니다.

 mkdir tokky && cd tokky && npm init -y

명령을 실행한 후 시스템은 다음과 같은 프로젝트에 대한 기본 package.json 파일을 생성했습니다.

 { "name": "tokky", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" }

이 가이드에서 package.json 파일은 올바른 구성을 보장하는 데 중요한 역할을 합니다. 이 시점에서 패키지의 노드 버전을 지정해 보겠습니다.

 echo "v18" > .nvmrc

다음을 사용하여 지정된 버전을 활성화하십시오.

 nvm use

README.md 파일의 경우:

 echo "# Tokky\n\nA simple zero dependency logger for node js." > README.md

마지막으로 개발 종속성을 설치합니다.

 npm i -D esbuild eslint prettier

초기 구성에서는 package.json 의 몇 가지 핵심 사항을 해결해야 합니다.

• main : 모듈의 기본 진입점을 지정합니다.
• bin : 여기서는 모듈이 제공하는 실행 파일을 지정합니다.
• files : 여기에는 패키지가 압축되고 이후에 npm 레지스트리에 게시될 때 포함될 파일 패턴 배열이 포함되어야 합니다.
• private : 패키지가 공개용이므로 false 로 설정해야 합니다.
• publishConfig : 이에 대한 액세스는 public 로 설정되어야 합니다.

이러한 구성 후에 package.json 은 다음과 유사해야 합니다.

 { "name": "tokky", "version": "1.0.0", "description": "Node js logger package", "main": "dist/index.js", "scripts": { "build": "esbuild src/index.js --bundle --platform=node --format=cjs --minify --outfile=dist/index.js", }, "files": [ "dist" ], "bin": { "tokky": "./dist/index.js" }, "keywords": [ "logger", "nodejs", "tokky" ], "private": false, "author": { "name": "Anton Kalik", "email": "[email protected]", "url": "https://idedy.com" }, "publishConfig": { "access": "public" }, "license": "MIT", "engines": { "node": "18.xx" }, "devDependencies": { "esbuild": "^0.19.2", "eslint": "^8.49.0", "prettier": "^3.0.3" } }

package.json 초기 설정 후

또한 두 개의 무시 파일을 추가해 보겠습니다.

 .idea node_modules dist

.gitignore

npm의 경우:

 .idea /src/ /node_modules/ /test/ /.nvmrc .github/

.npmignore

마지막으로 ESLint 설정에 대해 간략하게 설명하겠습니다. 그러나 구성은 패키지의 특정 요구 사항에 따라 달라질 수 있습니다.

 module.exports = { env: { browser: true, commonjs: true, es2021: true, node: true, }, extends: "eslint:recommended", overrides: [ { env: { node: true, }, files: ["src/**/*.js", ".eslintrc.{js,cjs}"], parserOptions: { sourceType: "script", }, }, ], parserOptions: { ecmaVersion: "latest", }, rules: {}, };

.eslintrc.js 구성

다음으로 GitHub로 이동하여 새 저장소를 설정하세요. 패키지 이름을 따서 이름을 지정하세요.

다음 명령을 실행하여 계속 진행합니다.

 git init git add . git commit -m "first commit" git branch -M main git remote add origin [email protected]:<your_github_username>/tokky.git git push -u origin main

패키지 소스

다음으로, 기본 애플리케이션을 제작하고 구축을 위해 설정해 보겠습니다. src 폴더 내에서 index.js 파일을 생성하고 다음 콘텐츠로 채웁니다.

 #!/usr/bin/env node const os = require('os'); const username = os.userInfo().username; if (process.argv[2] === 'hi') { console.log(`Hello ${username}`); }

패키지 예제를 위한 간단한 스크립트

개념은 간단합니다. my_package_name hi 실행하면 "Hello [username]"이 표시되어야 합니다.

이 기능을 검증하려면 다음을 사용하여 저장소에서 직접 명령을 실행하십시오.

 node src/index.js hi

출력이 기대와 일치하면 이제 소스를 빌드할 차례입니다.

 npm run build

이 명령을 성공적으로 실행하면 축소된 index.js 파일이 포함된 dist 폴더가 생성됩니다.

토큰

버전 범프를 결정하고 커밋 메시지를 기반으로 릴리스 프로세스를 처리하는 Semantic Release 실행이 올바르게 작동하려면 환경 변수( GITHUB_TOKEN , NPM_TOKEN )가 필요합니다. 토큰은 GitHub 비밀에서 가져오므로 기밀이 유지됩니다.

GITHUB_TOKEN 설정하려면 여기로 이동하세요. https://github.com/settings/tokens

드롭다운을 사용하여 토큰을 생성합니다. 새 개인 액세스 토큰(클래식)을 클릭하고 그림과 같이 권한을 설정합니다.

아래와 같이 패키지 이름을 사용하십시오.

생성된 토큰 값을 복사하고 기밀로 유지하십시오. 이를 다른 사람과 공유하지 않는 것이 중요합니다. Semantic Release CLI에 곧 필요하므로 이 토큰을 임시로 안전하게 저장하세요.

NPM_TOKEN 을 생성하려면 먼저 계정이 필요합니다. npm 공식 홈페이지 . 아직 등록하지 않으셨다면 등록절차를 진행해주세요. 그런 다음 다음으로 이동하십시오.

 https://www.npmjs.com/settings/<your_user_name>/tokens/new

"게시" 옵션을 사용하여 "클래식" 토큰을 생성합니다.

생성된 토큰 값을 복사하고 GitHub 비밀로 이동합니다.

 https://github.com/<your_user_name>/<your_repo_name>/settings/secrets/actions/new

저장소 비밀에 NPM_TOKEN 으로 새 비밀을 추가합니다.

이제 비밀이 설정되었으므로 GitHub Actions를 구성할 수 있습니다.

GitHub 액션 설정

프로세스를 자동화하기 위해 GitHub Actions를 사용할 예정입니다. 이는 GitHub에 통합된 CI/CD 도구입니다. 이를 통해 개발자는 GitHub 리포지토리에서 애플리케이션 구축, 테스트, 배포와 같은 워크플로를 직접 자동화할 수 있습니다. YAML 파일에서 워크플로를 정의함으로써 사용자는 푸시 및 풀 요청이나 예약된 시간과 같은 특정 이벤트를 기반으로 작업을 트리거할 수 있으므로 소프트웨어 개발 프로세스가 더욱 효율적이고 자동화됩니다.

시작하려면 프로젝트 루트에 .github 디렉터리를 만듭니다. 이 디렉터리 내에 workflows 하위 폴더를 설정합니다.

여기에서 release.yml 이라는 구성 파일을 만들고 다음 콘텐츠로 채웁니다.

 name: Release package on: push: branches: - main jobs: release: runs-on: ubuntu-latest if: ${{ github.ref == 'refs/heads/main' }} steps: - name: Checkout uses: actions/checkout@v3 - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: "18" - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Semantic Release run: npm run semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

이 워크플로는 기본 분기에 대한 푸시 이벤트를 트리거합니다. GitHub가 제공하는 최신 Ubuntu 가상 머신에서 작업을 실행하도록 구성되어 있습니다. 모든 직업을 탐구하는 것이 반드시 필요한 것은 아니지만 몇 가지 구체적인 직업을 집중 조명해 보겠습니다. 마지막으로 지정된 토큰을 사용하여 npm run semantic-release 호출하는 방법에 주목하세요.

의미론적 릴리스

자동화된 릴리스 프로세스에는 Semantic Release를 사용하겠습니다. 이 도구는 커밋 메시지 의미에 따라 버전 관리 및 패키지 게시를 처리합니다. 버전 범프(주요, 부 또는 패치)를 결정하려면 SemVer(의미적 버전 관리) 규칙을 따릅니다. 커밋 메시지를 분석함으로써 버전 관리의 수동 단계를 제거하고 일관된 버전 번호를 보장하며 릴리스 프로세스를 간소화합니다. 설정해 보겠습니다.

해당 설정을 위해 우리는 이 GitHub 코드 저장소에서 실행하세요.

 npx semantic-release-cli setup

그리고 다음 질문을 따르십시오.

 % npx semantic-release-cli setup ? What is your npm registry? https://registry.npmjs.org/ ? What is your npm username? your_user_name ? What is your npm password? [hidden] ? What is your NPM two-factor authentication code? 00000000 ? Provide a GitHub Personal Access Token (create a token at https://github.com/s ettings/tokens/new?scopes=repo) ghp_your_token_here ? What CI are you using? Github Actions

이미 개인 토큰이 있어야 합니다. 메시지가 나타나면 간단히 입력하세요. 마찬가지로, 우리가 설정한 GitHub Actions는 이전에 저장소 비밀에 설정한 NPM_TOKEN 활용합니다. 이제 package.json 을 확인하면 버전이 다음과 같이 표시됩니다.

 "version": "0.0.0-development",

그리고 새로운 스크립트:

 "semantic-release": "semantic-release"

이는 Semantic Release CLI에 의해 자동 생성되었습니다. 이 스크립트를 다음과 같이 개선해야 합니다.

 "semantic-release": "semantic-release --branches main"

이는 릴리스가 기본 분기에서만 이루어짐을 나타냅니다.

또한 Semantic Release는 package.json 의 repository 필드를 기반으로 설명을 생성합니다. 이 필드는 패키지 소스 코드의 위치에 대한 세부 정보를 제공합니다.

 "repository": { "type": "git", "url": "https://github.com/<your_github_username>/your_github_repo.git" }

이제 다음을 사용하여 모든 변경 사항을 푸시해 보겠습니다.

 git add . && git commit -m "semantic release" && git push

커밋 형식

시맨틱 릴리스는 구조화된 커밋 메시지의 규칙을 사용하여 버전 범프 유형(주요, 부 또는 패치)을 결정하고 변경 로그를 생성합니다. 이 커밋 규칙을 종종 "기존 커밋" 형식이라고 합니다.

이 구성에는 여러 플러그인이 필요합니다. package.json 에 다음 콘텐츠가 포함되어 있는지 확인하세요.

 "release": { "branches": [ { "name": "main" } ], "plugins": [ [ "@semantic-release/commit-analyzer", { "releaseRules": [ { "type": "feat", "release": "minor" }, { "type": "fix", "release": "patch" }, { "type": "refactor", "release": "patch" }, { "type": "build", "release": "patch" }, { "type": "chore", "release": "patch" }, { "type": "minor", "release": "patch" } ] } ], "@semantic-release/release-notes-generator", "@semantic-release/npm", "@semantic-release/github", [ "@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" } ] ] }

패키지.json

설정 커밋 형식 도구의 경우 다음을 사용하겠습니다. 커미티즌 . 설치하려면 다음 명령을 따르십시오.

 npx commitizen init cz-conventional-changelog --save-dev --save-exact

이 명령은 몇 분 정도 걸립니다. 그런 다음 package.json 을 새 스크립트로 업데이트합니다.

 "scripts": { // ... "commit": "cz" },

이제 그 스크립트를 활용할 시간입니다. git add . 그런 다음 npm run commit 실행하고 커밋에 필요한 세부 정보를 제공합니다.

그 모습은 다음과 같습니다.

 ? Select the type of change that you're committing: feat: A new feature ? What is the scope of this change (eg component or file name): (press enter to skip) commit ? Write a short, imperative tense description of the change (max 86 chars): (14) add commitizen ? Provide a longer description of the change: (press enter to skip) ? Are there any breaking changes? No ? Does this change affect any open issues? No

그런 다음 git push 수행하십시오.

GitHub 작업에서 자동화된 커밋 메시지 프로세스를 위한 나머지 패키지를 아직 설치하지 않았기 때문에 커밋이 실패한 것을 볼 수 있습니다.

 npm i -D @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/npm @semantic-release/changelog

대부분의 참조에서 종종 간과되는 중요한 단계는 워크플로 권한을 설정하는 것입니다. https://github.com/<your_user_name>/tokky/settings/actions 로 이동하여 GitHub 작업이 읽기 및 쓰기를 모두 허용하도록 권한을 구성합니다.

다음으로 상황을 조금 바꿔보겠습니다. 특정 키워드 feat: 와 메시지를 사용하여 커밋하세요.

 git add . && git commit -m "feat: my feature commit" && git push

package.json 내의 releaseRules 기억하시나요? 이러한 규칙은 패키지 릴리스 버전을 높이는 방법을 지정합니다. 이를 사용하면 feat , fix , refactor 등과 같은 특정 키워드를 사용하여 풀 요청을 생성할 수 있습니다. 이 풀 요청이 승인되고 이후에 메인 브랜치에 병합되면 트리거가 시작됩니다. 그런 다음 이 트리거는 GitHub 작업을 활성화하고 릴리스 프로세스를 자동화하며 패키지가 원활하게 업데이트되도록 합니다.

게시된 패키지

패키지가 성공적으로 게시되었으며 효율성을 위해 전체 프로세스가 자동화되었습니다. 게시를 확인하려면 npm 설정 https://www.npmjs.com/settings/<your_user_name>/packages 로 이동하여 패키지 섹션을 살펴보세요. 거기에서 새로 게시된 패키지를 찾을 수 있습니다.

이제 npx your_package_name hi 같은 간단한 명령을 사용하여 개발 테스트 결과를 즉시 확인할 수 있습니다. 또한 npm i -g your_package_name 명령을 사용하여 패키지를 전역적으로 설치할 수 있습니다.

결론

이 기사 전체에서 살펴본 것처럼 초기 설정에는 어려움이 많을 수 있지만 능률적이고 일관된 릴리스 프로세스를 구축하는 것이 보상입니다. GitHub Actions를 활용하면 이러한 복잡성이 단순화되어 개발자가 복잡한 물류보다는 코드 품질에 집중할 수 있습니다.

공개 패키지로 여정을 막 시작했거나 출판 노력에 차질이 발생한 경우, 체계적이고 자동화된 워크플로를 채택하는 데에는 부인할 수 없는 가치가 있습니다. Semantic Release를 통합함으로써 일관된 버전 관리를 보장하고 소프트웨어 개발에 대한 미래 지향적인 접근 방식을 옹호하게 됩니다.

원활한 게시, 골치 아픈 일 감소, 디지털 세계를 발전시키는 코드를 완성하는 데 더 많은 시간을 투자할 수 있습니다.

NPM_TOKEN 및 GITHUB_TOKEN 모두 GitHub Actions 내에서 적절한 권한을 부여받는 것이 중요합니다. 또한 package.json 은 publishConfig 액세스 설정으로 올바르게 구성되어야 하며 private 구성이 false 로 설정되어 있는지 확인해야 합니다. 문제가 발생하거나 통찰력이 있는 경우 주저하지 말고 의견을 보내주세요.

참고자료

저장소: https://github.com/antonkalik/tokky
의미론적 릴리스 CLI: https://github.com/semantic-release/cli
약속: https://github.com/commitizen/cz-cli