Cách triển khai bản phát hành ngữ nghĩa cho các gói công khai không có phạm vi

Hướng dẫn chi tiết về cách xuất bản gói công khai không có phạm vi bằng cách sử dụng bản phát hành ngữ nghĩa tận dụng sức mạnh của GitHub Actions

Trong bối cảnh phát triển phần mềm ngày càng phát triển, việc duy trì tính nhất quán của phiên bản và tự động hóa quy trình phát hành là quan trọng hơn bao giờ hết. Đi vào Phát hành ngữ nghĩa : một công cụ được thiết kế để đảm bảo phiên bản rõ ràng và có cấu trúc. Đối với các nhà phát triển tận dụng các gói công khai không có phạm vi, quá trình này có vẻ khó khăn. Tuy nhiên, với sức mạnh của các hành động GitHub trong tầm tay, việc tự động hóa trở nên dễ dàng.

Bài viết này cung cấp hướng dẫn chi tiết và toàn diện, hướng dẫn từng bước để tích hợp liền mạch Bản phát hành ngữ nghĩa vào quy trình làm việc của bạn, được thiết kế riêng cho những người sử dụng các gói công khai không có phạm vi. Đi sâu vào và khám phá cách tiếp cận hợp lý để phát hành phần mềm.

Khi tôi tạo gói công cộng , Tôi đã gặp phải trở ngại trong việc xuất bản nó một cách liền mạch lên NPM. Đó là một thách thức để đảm bảo cấu hình phù hợp.

Để hiểu rõ hơn, chúng ta hãy trải nghiệm từng bước để xuất bản các gói công khai phù hợp tới NPM .

Tổng quan về nội dung

• Đặt tên cho gói
• Tạo một gói
• Nguồn gói
• Mã thông báo
• Thiết lập hành động GitHub
• Phát hành ngữ nghĩa
• Định dạng cam kết
• Gói xuất bản
• Phần kết luận

Đặt tên cho gói

Trước khi bắt đầu triển khai gói của chúng tôi, tốt hơn hết bạn nên tìm tên thích hợp cho gói đó. Để chắc chắn rằng tên đó chưa được sử dụng — hãy kiểm tra my_package_name và lấy nó cho gói của bạn. Tôi đã chọn “tokky.” Từ thời điểm đó, việc đặt tên gói là không thể. Đối với tên trong npm, bạn phải xuất bản gói.

Tạo một gói

Mục tiêu là phát triển một gói đơn giản để xuất nội dung ra bảng điều khiển. Chúng ta cần đảm bảo rằng chúng ta có thể cài đặt và chạy nó. Đối với quá trình xây dựng, hãy sử dụng đơn giản xây dựng .

Trong bài viết này, tôi sẽ sử dụng tên của gói tokky . Hãy tạo package.json với dữ liệu ban đầu.

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

Sau khi thực thi lệnh, hệ thống sẽ tạo một tệp package.json mặc định cho dự án, trông như thế này:

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

Trong hướng dẫn này, tệp package.json đóng một vai trò quan trọng trong việc đảm bảo cấu hình phù hợp. Tại thời điểm này, hãy chỉ định phiên bản nút cho gói của chúng tôi:

 echo "v18" > .nvmrc

và kích hoạt phiên bản được chỉ định bằng cách sau:

 nvm use

Đối với tệp README.md :

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

Cuối cùng, cài đặt các phần phụ thuộc phát triển:

 npm i -D esbuild eslint prettier

Trong cấu hình ban đầu, chúng ta cần giải quyết một số điểm chính trong package.json :

• main : Điều này chỉ định điểm vào chính cho mô-đun.
• bin : Tại đây, bạn sẽ chỉ định bất kỳ tệp thực thi nào mà mô-đun của bạn cung cấp.
• files : Cái này phải chứa một mảng các mẫu tệp sẽ được đưa vào khi gói được đóng gói và sau đó được xuất bản lên sổ đăng ký npm.
• private : Đảm bảo điều này được đặt thành false vì gói của chúng tôi được dự định là công khai.
• publishConfig : Quyền truy cập này phải được đặt thành public .

Sau những cấu hình này, package.json của bạn sẽ giống như sau:

 { "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" } }

pack.json sau khi thiết lập ban đầu

Ngoài ra, hãy thêm hai tệp bỏ qua:

 .idea node_modules dist

.gitignore

và cho npm:

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

.npmignore

Cuối cùng, tôi sẽ phác thảo cách thiết lập ESLint của mình. Tuy nhiên, hãy nhớ rằng cấu hình có thể thay đổi tùy theo yêu cầu cụ thể của gói của bạn.

 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: {}, };

Cấu hình .eslintrc.js

Tiếp theo, hãy đến GitHub và thiết lập một kho lưu trữ mới. Đặt tên nó theo tên gói của bạn.

Tiến hành bằng cách thực hiện các lệnh tiếp theo:

 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

Nguồn gói

Tiếp theo, hãy tạo một ứng dụng cơ bản và thiết lập nó để xây dựng. Bên trong thư mục src , tạo một tệp index.js và điền nội dung sau vào đó:

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

Tập lệnh đơn giản cho ví dụ về gói

Khái niệm này rất đơn giản: thực thi my_package_name hi sẽ hiển thị “Xin chào [tên người dùng].”

Để xác thực chức năng này, hãy thực thi lệnh trực tiếp từ kho lưu trữ của bạn bằng cách sử dụng:

 node src/index.js hi

Nếu kết quả đầu ra phù hợp với mong đợi thì đã đến lúc xây dựng nguồn:

 npm run build

Chạy thành công lệnh này sẽ tạo ra một thư mục dist chứa tệp index.js được rút gọn.

Mã thông báo

Thực thi Bản phát hành ngữ nghĩa, sẽ xác định các lỗi phiên bản và xử lý quá trình phát hành dựa trên thông báo cam kết, yêu cầu các biến môi trường ( GITHUB_TOKEN , NPM_TOKEN ) để hoạt động chính xác. Mã thông báo được lấy từ bí mật của GitHub, đảm bảo chúng được giữ bí mật.

Để đặt GITHUB_TOKEN , hãy điều hướng tại đây: https://github.com/settings/tokens

Tạo mã thông báo bằng cách sử dụng menu thả xuống. Nhấp vào mã thông báo truy cập cá nhân mới (cổ điển) và đặt quyền như trong hình.

Sử dụng tên gói của bạn như hiển thị bên dưới:

Sau khi được tạo, hãy sao chép giá trị mã thông báo và giữ bí mật — điều quan trọng là không chia sẻ thông tin này với người khác. Tạm thời lưu trữ mã thông báo này một cách an toàn vì chúng tôi sẽ sớm cần nó cho CLI bản phát hành ngữ nghĩa.

Để tạo NPM_TOKEN , trước tiên bạn cần có tài khoản trên trang web chính thức của npm . Nếu bạn chưa đăng ký, hãy thực hiện quá trình đăng ký. Sau đó, điều hướng đến:

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

và tạo mã thông báo “cổ điển” với tùy chọn “xuất bản”.

Sao chép giá trị được tạo của mã thông báo và điều hướng đến bí mật GitHub:

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

và đặt bí mật mới là NPM_TOKEN vào kho lưu trữ bí mật:

Với các bí mật của chúng tôi hiện đã được thiết lập, chúng tôi có thể định cấu hình Tác vụ GitHub.

Thiết lập hành động GitHub

Để tự động hóa các quy trình của chúng tôi, chúng tôi sẽ sử dụng GitHub Actions. Đây là công cụ CI/CD được tích hợp trong GitHub. Nó cho phép các nhà phát triển tự động hóa quy trình làm việc trực tiếp từ kho GitHub của họ, chẳng hạn như xây dựng, thử nghiệm và triển khai ứng dụng. Bằng cách xác định quy trình làm việc trong tệp YAML, người dùng có thể kích hoạt các hành động dựa trên các sự kiện cụ thể như yêu cầu đẩy và kéo hoặc thời gian đã lên lịch, giúp quá trình phát triển phần mềm hiệu quả và tự động hơn.

Để bắt đầu, hãy tạo một thư mục .github ở thư mục gốc của dự án của bạn. Trong thư mục này, hãy thiết lập thư mục con quy trình workflows .

Tại đây, hãy tạo tệp cấu hình của chúng tôi có tên release.yml và điền vào đó nội dung sau:

 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 }}

Quy trình làm việc này kích hoạt một sự kiện đẩy tới nhánh chính. Nó được cấu hình để chạy công việc trên máy ảo Ubuntu mới nhất mà GitHub cung cấp. Mặc dù không nhất thiết phải đi sâu vào mọi công việc nhưng hãy nêu bật một số công việc cụ thể. Ở phần cuối, hãy lưu ý cách chúng tôi gọi npm run semantic-release bằng cách sử dụng các mã thông báo được chỉ định.

Phát hành ngữ nghĩa

Đối với quy trình phát hành tự động, chúng tôi sẽ sử dụng Bản phát hành ngữ nghĩa. Công cụ này xử lý việc lập phiên bản và xuất bản gói dựa trên ngữ nghĩa của thông báo cam kết. Nó tuân theo các quy ước của Phiên bản ngữ nghĩa (SemVer) để xác định các lỗi phiên bản (chính, phụ hoặc bản vá). Bằng cách phân tích các thông báo cam kết, nó giúp loại bỏ các bước lập phiên bản thủ công, đảm bảo số phiên bản nhất quán và hợp lý hóa quy trình phát hành. Hãy thiết lập nó.

Đối với thiết lập đó, chúng tôi sẽ sử dụng mã GitHub này và chạy nó trên kho lưu trữ của bạn:

 npx semantic-release-cli setup

Và làm theo các câu hỏi:

 % 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

Bạn đã có Mã thông báo cá nhân của mình. Đơn giản chỉ cần nhập nó khi được nhắc. Tương tự, các Hành động GitHub mà chúng tôi đã thiết lập sẽ sử dụng NPM_TOKEN mà chúng tôi đã thiết lập trước đó trong kho lưu trữ bí mật. Nếu bây giờ bạn kiểm tra package.json , phiên bản sẽ hiển thị dưới dạng:

 "version": "0.0.0-development",

và kịch bản mới:

 "semantic-release": "semantic-release"

được tạo tự động bởi CLI phát hành ngữ nghĩa. Chúng tôi sẽ cần nâng cao tập lệnh này như sau:

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

Điều này chỉ ra rằng các bản phát hành sẽ chỉ được thực hiện từ nhánh chính.

Ngoài ra, Bản phát hành ngữ nghĩa tạo mô tả dựa trên trường repository trong package.json của bạn. Trường này cung cấp chi tiết về vị trí mã nguồn của gói.

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

Bây giờ, hãy đẩy tất cả các thay đổi của chúng ta bằng:

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

Định dạng cam kết

Bản phát hành ngữ nghĩa dựa trên quy ước của các thông báo cam kết có cấu trúc để xác định loại lỗi phiên bản (chính, phụ hoặc bản vá) và tạo nhật ký thay đổi. Quy ước cam kết này thường được gọi là định dạng “Cam kết thông thường”.

Đối với cấu hình này, chúng tôi sẽ cần một số plugin. Đảm bảo package.json của bạn chứa nội dung sau:

 "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" } ] ] }

gói.json

Đối với công cụ định dạng cam kết thiết lập, chúng tôi sẽ sử dụng người cam kết . Để cài đặt nó, hãy làm theo lệnh này:

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

Lệnh này sẽ mất một vài phút. Sau đó cập nhật package.json của bạn bằng một tập lệnh mới:

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

và đã đến lúc sử dụng tập lệnh đó. Bắt đầu bằng cách thực thi git add . , sau đó chạy npm run commit và cung cấp các chi tiết cần thiết cho cam kết của bạn.

Đây là những gì trông giống như:

 ? 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

Sau đó, thực hiện git push .

Trong các hành động của GitHub, bạn sẽ thấy rằng cam kết của chúng tôi không thành công vì chúng tôi vẫn chưa cài đặt các gói còn lại cho quy trình thông báo cam kết tự động.

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

Một bước quan trọng, thường bị bỏ qua trong hầu hết các tài liệu tham khảo, là thiết lập các quyền của quy trình làm việc. Điều hướng đến https://github.com/<your_user_name>/tokky/settings/actions và định cấu hình các quyền để cho phép các hành động GitHub vừa đọc và ghi.

Tiếp theo, hãy thay đổi mọi thứ một chút. Cam kết với một từ khóa cụ thể, feat: , theo sau là tin nhắn của bạn.

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

Bạn có nhớ releaseRules trong package.json không? Những quy tắc này quy định cách chúng tôi tăng phiên bản phát hành gói của mình. Với điều này, bạn có thể tạo yêu cầu kéo bằng cách sử dụng các từ khóa cụ thể như feat , fix , refactor , v.v. Khi yêu cầu kéo này được phê duyệt và sau đó được hợp nhất vào nhánh chính, nó sẽ bắt đầu kích hoạt. Sau đó, trình kích hoạt này sẽ kích hoạt hành động GitHub, tự động hóa quy trình phát hành và đảm bảo gói của bạn được cập nhật liền mạch.

Gói xuất bản

Gói đã được xuất bản thành công và toàn bộ quá trình đã được tự động hóa để đạt hiệu quả. Để xác nhận xuất bản, hãy đi tới cài đặt npm của bạn https://www.npmjs.com/settings/<your_user_name>/packages và xem phần gói; ở đó, bạn sẽ tìm thấy gói mới được xuất bản của mình.

Giờ đây, với một lệnh đơn giản như npx your_package_name hi , bạn có thể xem ngay kết quả thử nghiệm phát triển của chúng tôi. Ngoài ra, gói có thể được cài đặt trên toàn cầu bằng lệnh npm i -g your_package_name .

Phần kết luận

Như chúng ta đã thấy trong suốt bài viết này, mặc dù các thiết lập ban đầu có thể gặp nhiều thách thức nhưng phần thưởng nằm ở việc thiết lập một quy trình phát hành hợp lý và nhất quán. Việc tận dụng GitHub Actions sẽ đơn giản hóa những sự phức tạp này, đảm bảo các nhà phát triển có thể tập trung vào chất lượng mã thay vì những rắc rối về hậu cần.

Cho dù bạn mới bắt đầu hành trình với các gói công khai hay đã gặp phải trở ngại trong nỗ lực xuất bản của mình thì việc áp dụng quy trình làm việc tự động, có cấu trúc đều có giá trị không thể phủ nhận. Bằng cách tích hợp Bản phát hành ngữ nghĩa, bạn đang đảm bảo việc tạo phiên bản nhất quán và thúc đẩy cách tiếp cận tương lai để phát triển phần mềm.

Đây là cách xuất bản liền mạch, ít đau đầu hơn và dành nhiều thời gian hơn để hoàn thiện mã thúc đẩy thế giới kỹ thuật số của chúng ta phát triển.

Hãy nhớ rằng, điều cần thiết là cả NPM_TOKEN và GITHUB_TOKEN đều được cấp các quyền thích hợp trong Hành động GitHub. Ngoài ra, package.json của bạn phải được định cấu hình chính xác với các cài đặt để truy cập publishConfig và đảm bảo rằng cấu hình private được đặt thành false . Nếu bạn gặp bất kỳ vấn đề nào hoặc có hiểu biết sâu sắc, xin vui lòng bình luận.

Người giới thiệu

Kho: https://github.com/antonkalik/tokky
CLI phát hành ngữ nghĩa: https://github.com/semantic-release/cli
Người cam kết: https://github.com/commitizen/cz-cli