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 : 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. Phát hành ngữ nghĩa 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 , 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. gói công cộng Để 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 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. my_package_name 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 . Hãy tạo với dữ liệu ban đầu. tokky package.json mkdir tokky && cd tokky && npm init -y Sau khi thực thi lệnh, hệ thống sẽ tạo một tệp mặc định cho dự án, trông như thế nà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" } Trong hướng dẫn này, tệp đó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: package.json 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 : Điều này chỉ định điểm vào chính cho mô-đun. main : 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. bin : 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. files : Đảm bảo điều này được đặt thành vì gói của chúng tôi được dự định là công khai. private false : Quyền truy cập này phải được đặt thành . publishConfig public Sau những cấu hình này, của bạn sẽ giống như sau: 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": "antonkalik@gmail.com", "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 git@github.com:<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 , tạo một tệp và điền nội dung sau vào đó: 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}`); } 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 sẽ hiển thị “Xin chào [tên người dùng].” my_package_name hi Để 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 chứa tệp được rút gọn. dist index.js 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 ( , ) để 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. GITHUB_TOKEN NPM_TOKEN Để đặt , hãy điều hướng tại đây: GITHUB_TOKEN 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 , trước tiên bạn cần có tài khoản trên . 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: NPM_TOKEN trang web chính thức của npm 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à vào kho lưu trữ bí mật: NPM_TOKEN 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ụ đượ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. CI/CD Để bắt đầu, hãy tạo một thư mục ở 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 . .github workflows Tại đây, hãy tạo tệp cấu hình của chúng tôi có tên và điền vào đó nội dung sau: 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 }} 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 bằng cách sử dụng các mã thông báo được chỉ định. npm run semantic-release 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 và chạy nó trên kho lưu trữ của bạn: mã GitHub này 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 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 , phiên bản sẽ hiển thị dưới dạng: NPM_TOKEN package.json "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 trong 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 package.json "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 của bạn chứa nội dung sau: 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" } ] ] } 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 . Để cài đặt nó, hãy làm theo lệnh này: người cam kết 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 của bạn bằng một tập lệnh mới: package.json "scripts": { // ... "commit": "cz" }, và đã đến lúc sử dụng tập lệnh đó. Bắt đầu bằng cách thực thi , sau đó chạy và cung cấp các chi tiết cần thiết cho cam kết của bạn. git add . npm run commit Đâ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 Điều hướng đến và định cấu hình các quyền để cho phép các hành động GitHub vừa đọc và ghi. 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. https://github.com/<your_user_name>/tokky/settings/actions 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ể, , theo sau là tin nhắn của bạn. feat: git add . && git commit -m "feat: my feature commit" && git push Bạn có nhớ trong 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ư , , , 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. releaseRules package.json feat fix refactor 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 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. https://www.npmjs.com/settings/<your_user_name>/packages Giờ đây, với một lệnh đơn giản như , 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 . npx your_package_name hi 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ả và đều được cấp các quyền thích hợp trong Hành động GitHub. Ngoài ra, 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 và đảm bảo rằng cấu hình được đặt thành . 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. NPM_TOKEN GITHUB_TOKEN package.json publishConfig private false Người giới thiệu Kho: CLI phát hành ngữ nghĩa: Người cam kết: https://github.com/antonkalik/tokky https://github.com/semantic-release/cli https://github.com/commitizen/cz-cli Cũng được xuất bản . ở đây Nhờ vào Harper chủ nhật từ Unsplash cho hình ảnh chính.
