Herkese Açık Kapsamlı Olmayan Paketler için Semantik Sürüm Nasıl Uygulanır?

GitHub Eylemlerinin gücünden yararlanarak anlamsal yayın kullanarak kapsamlı olmayan bir genel paketin yayınlanmasına ilişkin ayrıntılı talimatlar

Gelişen yazılım geliştirme ortamında sürüm tutarlılığını korumak ve sürüm sürecini otomatikleştirmek her zamankinden daha önemli. Girmek Anlamsal Sürüm : Açık ve yapılandırılmış sürüm oluşturmayı sağlamak için tasarlanmış bir araç. Kapsam dışı genel paketlerden yararlanan geliştiriciler için süreç göz korkutucu görünebilir. Ancak GitHub eylemlerinin gücü parmaklarımızın ucunda olduğundan otomasyon çocuk oyuncağı haline gelir.

Bu makale, Semantic Release'i iş akışınıza sorunsuz bir şekilde entegre etmek için adım adım talimatlar sağlayan, genel kapsamlı olmayan paketleri kullananlar için özel olarak tasarlanmış ayrıntılı ve kapsamlı bir kılavuz sunmaktadır. Yazılım sürümlerine yönelik kolaylaştırılmış yaklaşımı keşfedin ve keşfedin.

Kendimi yarattığımda genel paket , onu sorunsuz bir şekilde NPM'ye yayınlamakta engellerle karşılaştım. Doğru konfigürasyonları sağlamak zorlu bir işti.

Bunu başarmak için, halka açık paketlerin doğru şekilde yayınlanmasına yönelik adım adım deneyime bakalım. NPM .

İçeriğe Genel Bakış

• Paketi adlandırın
• Paket oluştur
• Paket kaynağı
• Jetonlar
• GitHub Eylemleri kurulumu
• Anlamsal sürüm
• Kaydetme biçimi
• Yayınlanan paket
• Çözüm

Paketi adlandırın

Paketimizi uygulamaya geçmeden önce ona uygun adı bulmak daha iyidir. Adın önceden alınmadığından emin olmak için my_package_name kontrol edin ve paketiniz için alın. "Tokky"yi seçtim. Bu noktadan sonra paketin adını ayırtmak imkansızdır. Npm'deki ad için paketi yayınlamanız gerekir.

Paket oluştur

Amaç, içeriği konsola aktaran basit bir paket geliştirmektir. Onu kurabildiğimizden ve çalıştırabildiğimizden emin olmalıyız. Derleme süreci için basit olanı kullanalım esbuild .

Bu yazı boyunca tokky paketinin adını kullanacağım. Başlangıç verileriyle package.json dosyasını oluşturalım.

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

Komutu yürüttükten sonra sistem, proje için şuna benzeyen varsayılan bir package.json dosyası oluşturdu:

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

Bu kılavuzda package.json dosyası doğru yapılandırmanın sağlanmasında çok önemli bir rol oynamaktadır. Bu noktada paketimizin node versiyonunu belirtelim:

 echo "v18" > .nvmrc

ve belirtilen sürümü aşağıdakilerle etkinleştirin:

 nvm use

README.md dosyası için:

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

Son olarak geliştirme bağımlılıklarını yükleyin:

 npm i -D esbuild eslint prettier

İlk yapılandırmamızda package.json dosyasındaki birkaç önemli noktaya değinmemiz gerekiyor:

• main : Bu, modülün birincil giriş noktasını belirtir.
• bin : Burada modülünüzün sağladığı yürütülebilir dosyaları belirteceksiniz.
• files : Bu, paket paketlendiğinde ve daha sonra npm kayıt defterinde yayınlandığında dahil edilecek bir dizi dosya deseni içermelidir.
• private : Paketimizin herkese açık olması amaçlandığından bunun false olarak ayarlandığından emin olun.
• publishConfig : Bunun için erişim public olarak ayarlanmalıdır.

Bu yapılandırmalardan sonra package.json dosyanız aşağıdakine benzemelidir:

 { "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 ilk kurulumdan sonra

Ek olarak iki yoksayma dosyası ekleyelim:

 .idea node_modules dist

.gitignore

ve npm için:

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

.npmignore

Son olarak ESLint kurulumumu özetleyeceğim. Ancak paketinizin özel gereksinimlerine göre yapılandırmanın değişebileceğini unutmayı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: {}, };

.eslintrc.js yapılandırması

Daha sonra GitHub'a gidin ve yeni bir depo oluşturun. Paketinizin adını verin.

Sonraki komutları yürüterek devam edin:

 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

Paket kaynağı

Sonra, temel bir uygulama oluşturalım ve onu oluşturmak için ayarlayalım. src klasörünün içinde bir index.js dosyası oluşturun ve onu aşağıdaki içerikle doldurun:

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

Paket örneği için basit komut dosyası

Konsept basittir: my_package_name hi çalıştırıldığında "Merhaba [kullanıcı adı]" görüntülenmelidir.

Bu işlevselliği doğrulamak için aşağıdakileri kullanarak komutu doğrudan deponuzdan yürütün:

 node src/index.js hi

Çıktı beklentilerle uyumluysa kaynağı oluşturmanın zamanı gelmiştir:

 npm run build

Bu komutu başarıyla çalıştırmak, küçültülmüş bir index.js dosyasını içeren bir dist klasörü oluşturacaktır.

Jetonlar

Sürüm artışlarını belirleyecek ve yayınlama sürecini taahhüt mesajlarına göre yönetecek Semantic Release'i yürütme, ortam değişkenlerinin ( GITHUB_TOKEN , NPM_TOKEN ) doğru şekilde çalışmasını gerektirir. Tokenlar GitHub sırlarından alınır ve gizli kalmaları sağlanır.

GITHUB_TOKEN ayarlamak için buraya gidin: https://github.com/settings/tokens

Açılır menüyü kullanarak belirteci oluşturun. Yeni kişisel erişim belirtecine (klasik) tıklayın ve izni resimdeki gibi ayarlayın.

Paket adınızı aşağıda gösterildiği gibi kullanın:

Belirteç değeri oluşturulduktan sonra kopyalayın ve gizli tutun; bunu başkalarıyla paylaşmamak çok önemlidir. Semantic Release CLI için kısa süre içinde ihtiyacımız olacağından bu belirteci geçici olarak güvenli bir şekilde saklayın.

NPM_TOKEN oluşturmak için öncelikle bir hesaba ihtiyacınız var npm'nin resmi web sitesi . Henüz kayıt olmadıysanız kayıt işlemini gerçekleştirin. Bundan sonra şuraya gidin:

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

ve "yayınla" seçeneğiyle "klasik" bir token oluşturun.

Belirtecin oluşturulan değerini kopyalayın ve GitHub gizli dizilerine gidin:

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

ve depo sırlarına NPM_TOKEN olarak yeni sır koyun:

Sırlarımız artık ayarlandığında GitHub Eylemlerini yapılandırabiliriz.

GitHub Eylemleri kurulumu

Süreçlerimizi otomatikleştirmek için GitHub Actions'ı kullanacağız. Bu, GitHub'a entegre edilmiş bir CI/CD aracıdır. Geliştiricilerin uygulama oluşturma, test etme ve dağıtma gibi iş akışlarını doğrudan GitHub depolarından otomatikleştirmesine olanak tanır. Kullanıcılar, YAML dosyalarındaki iş akışlarını tanımlayarak, itme ve çekme istekleri veya planlanmış zamanlar gibi belirli olaylara dayalı eylemleri tetikleyebilir, böylece yazılım geliştirme sürecini daha verimli ve otomatik hale getirebilirler.

Başlamak için projenizin kökünde bir .github dizini oluşturun. Bu dizin içinde bir workflows alt klasörü oluşturun.

Burada, release.yml adlı yapılandırma dosyamızı oluşturun ve onu aşağıdaki içerikle doldurun:

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

Bu iş akışı ana dalda bir push olayını tetikler. İşi GitHub'ın sunduğu en son Ubuntu sanal makinesinde çalıştıracak şekilde yapılandırılmıştır. Her işi derinlemesine incelemek zorunlu olmasa da, bazı spesifik işleri öne çıkaralım. Sonlara doğru, belirlenen belirteçleri kullanarak npm run semantic-release nasıl çağırdığımıza dikkat edin.

Anlamsal sürüm

Otomatik sürüm süreci için Semantic Release kullanacağız. Bu araç, taahhüt mesajı semantiğine dayalı olarak sürüm oluşturma ve paket yayınlamayı yönetir. Sürüm artışlarını (büyük, küçük veya yama) belirlemek için Anlamsal Sürüm Oluşturma (SemVer) kurallarına uyar. Onaylama mesajlarını analiz ederek manuel sürüm oluşturma adımlarını ortadan kaldırır, tutarlı sürüm numaraları sağlar ve sürüm sürecini kolaylaştırır. Hadi ayarlayalım.

Bu kurulum için kullanacağız bu GitHub kodu ve deponuzda çalıştırın:

 npx semantic-release-cli setup

Ve şu soruları takip edin:

 % 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

Kişisel Simgenize zaten sahip olmalısınız. İstendiğinde girmeniz yeterlidir. Benzer şekilde, oluşturduğumuz GitHub Eylemleri, daha önce depo sırlarında oluşturduğumuz NPM_TOKEN kullanacaktır. Şimdi package.json dosyanızı kontrol ederseniz sürüm şu şekilde görünecektir:

 "version": "0.0.0-development",

ve yeni komut dosyası:

 "semantic-release": "semantic-release"

Semantic Release CLI tarafından otomatik olarak oluşturulmuştur. Bu betiği aşağıdaki gibi geliştirmemiz gerekecek:

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

Bu da yayınların sadece ana şubeden yapılacağını gösteriyor.

Ayrıca Semantic Release, package.json dosyanızdaki repository alanını temel alan bir açıklama oluşturur. Bu alan paketin kaynak kodunun konumu hakkında ayrıntılar sunar.

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

Şimdi tüm değişikliklerimizi şununla aktaralım:

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

Kaydetme biçimi

Semantic Release, sürüm artışının türünü (majör, minör veya yama) belirlemek ve değişiklik günlükleri oluşturmak için yapılandırılmış taahhüt mesajları geleneğine dayanır. Bu taahhüt sözleşmesine genellikle “Geleneksel Taahhütler” formatı denir.

Bu yapılandırma için birkaç eklentiye ihtiyacımız olacak. package.json dosyanızın aşağıdaki içeriği içerdiğinden emin olun:

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

paket.json

Kurulum taahhüt formatı aracı için kullanacağız taahhüt etmek . Yüklemek için şu komutu izleyin:

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

Bu komut birkaç dakika sürecektir. Ardından package.json dosyanızı yeni bir komut dosyasıyla güncelleyin:

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

ve bu betiği kullanmanın zamanı geldi. git add . , ardından npm run commit çalıştırın ve taahhüdünüz için gerekli ayrıntıları sağlayın.

İşte neye benziyor:

 ? 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

Bundan sonra git push yapın.

GitHub eylemlerinde, otomatik taahhüt mesajı süreci için geri kalan paketleri hala kurmadığımız için taahhütümüzün başarısız olduğunu göreceksiniz.

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

Çoğu referansta sıklıkla gözden kaçırılan önemli bir adım, iş akışı izinlerinin ayarlanmasıdır. https://github.com/<your_user_name>/tokky/settings/actions adresine gidin ve GitHub eylemlerinin hem okuma hem de yazmasına izin verecek şekilde izinleri yapılandırın.

Sonra, işleri biraz değiştirelim. Belirli bir anahtar kelime olan feat: ile ve ardından mesajınızla taahhütte bulunun.

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

package.json içindeki releaseRules hatırlıyor musunuz? Bu kurallar, paket sürümümüzün sürümünü nasıl artıracağımızı belirler. Bunu yerine getirdiğinizde, feat , fix , refactor vb. gibi belirli anahtar kelimeleri kullanarak bir çekme isteği oluşturabilirsiniz. Bu çekme isteği onaylandıktan ve ardından ana dalla birleştirildikten sonra bir tetikleyici başlatılır. Bu tetikleyici daha sonra GitHub eylemini etkinleştirir, sürüm sürecini otomatikleştirir ve paketinizin sorunsuz bir şekilde güncellenmesini sağlar.

Yayınlanan paket

Paket başarıyla yayınlandı ve verimlilik amacıyla tüm süreç otomatikleştirildi. Yayını onaylamak için https://www.npmjs.com/settings/<your_user_name>/packages npm ayarlarınıza gidin ve paketler bölümüne bakın; orada yeni yayınlanan paketinizi bulacaksınız.

Artık npx your_package_name hi gibi basit bir komutla geliştirme testlerimizin sonuçlarını anında görebilirsiniz. Ayrıca paket, npm i -g your_package_name komutu kullanılarak genel olarak kurulabilir.

Çözüm

Bu makale boyunca gördüğümüz gibi, ilk kurulumlar zorluklarla dolu olsa da ödül, akıcı ve tutarlı bir sürüm süreci oluşturmaktır. GitHub Eylemlerinden yararlanmak, bu karmaşıklıkları basitleştirerek geliştiricilerin lojistik karmaşıklıklar yerine kod kalitesine odaklanabilmesini sağlar.

İster herkese açık paketlerle yolculuğunuza yeni başlıyor olun ister yayınlama çalışmalarınızda aksaklıklarla karşılaşmış olun, yapılandırılmış, otomatikleştirilmiş bir iş akışını benimsemenin yadsınamaz bir değeri vardır. Semantic Release'i entegre ederek tutarlı sürüm oluşturmayı garantiliyor ve yazılım geliştirmede ileriye dönük bir yaklaşımı destekliyorsunuz.

Sorunsuz yayıncılığa, daha az baş ağrısına ve dijital dünyamızı ileriye taşıyan kodu mükemmelleştirmek için daha fazla zaman harcamaya hazırız.

GitHub Eylemlerinde hem NPM_TOKEN hem de GITHUB_TOKEN uygun izinlerin verilmesinin önemli olduğunu unutmayın. Ek olarak package.json dosyanız, publishConfig erişimine yönelik ayarlarla doğru şekilde yapılandırılmalı ve private yapılandırmanın false olarak ayarlandığından emin olunmalıdır. Herhangi bir sorunla karşılaşırsanız veya görüşleriniz varsa, lütfen yorum yapmaktan çekinmeyin.

Referanslar

Depo: https://github.com/antonkalik/tokky
Semantik Sürüm CLI'si: https://github.com/semantic-release/cli
Taahhüt: https://github.com/commitizen/cz-cli