npm'ye Yayınlama ve Anlamsal Sürümleme

Yayımlamadan önce her zaman npm publish --dry-run komutunu çalıştırın. Bu, hiçbir şeyi gerçekten yüklemeden yayımlama işlemini simüle eder; tam olarak hangi dosyaların dahil edileceğini, boyutlarını ve paket tar arşivinin içeriğini gösterir. Kaynak dosyalarını yanlışlıkla dahil etmek veya dist dizinini eksik bırakmak gibi yaygın hataları yakalar.

files alanını package.json içinde kullanarak yayımlanacak içerikleri denetleyin: "files": ["dist", "README.md"]. Bu beyaz liste yaklaşımı, .npmignore'dan (kara liste olan ve eklemeyi unuttuğunuzda hassas dosyaların sızmasına neden olabilen) daha güvenlidir. dist dizinini, tür bildirimlerini ve belgeleri her zaman dahil edin. src, sınamalar veya node_modules dizinlerini asla dahil etmeyin.

npm paketleri anlamsal sürümleme (semver) kurallarını izler: MAJOR.MINOR.PATCH. Geriye dönük uyumluluğu bozan değişiklikler (özellikleri kaldırma, API imzalarını değiştirme) için MAJOR sürüm numarasını artırın. Yeni, geriye dönük uyumlu özellikler (yeni bileşenler, yeni isteğe bağlı özellikler) için MINOR sürüm numarasını artırın. Geriye dönük uyumlu hata düzeltmeleri için PATCH sürümünü artırın. 0.x.x sürümü, her şeyin bozulabileceği kararlı öncesi bir sürüm olarak kabul edilir.

Ön sürüm tanımlayıcıları, bir sürümün üretime hazır olmadığını belirtir: 1.0.0-alpha.1 erken deneysel derlemeler, 1.0.0-beta.2 özellikleri tamamlanmış ancak hatalar içerebilecek sürümler ve 1.0.0-rc.1 (sürüm adayı) son sınamalara hazır sürümler için kullanılır. Ön sürümleri npm publish --tag beta komutuyla yayımlayın; böylece varsayılan kurulum haline gelmezler.

Changesets, bileşen kitaplıklarında paket sürümlemesini ve değişiklik günlüklerini yönetmek için kullanılan standart araçtır. İş akışı şöyledir: katkı sağlayanlar, neyin değiştiğini ve değişiklik türünü (ana/küçük/yama) kaydetmek için yarn changeset add komutunu çalıştırır. CI, paket sürümlerini artırmak için yarn changeset version komutunu çalıştırır. Yayımlama adımı, npm'e göndermek için yarn changeset publish komutunu çalıştırır.

Changesets, katkı sağlayanların gönderdiği değişiklik kümesi dosyalarına dayanarak CHANGELOG.md dosyasını otomatik olarak oluşturur ve güncel tutar. Her kayıt; sürüm numarasını, yayımlanma tarihini ve değişiklik açıklamalarını içerir. Böylece elle değişiklik günlüğü bakımı gerektirmeden her sürümün insanlar tarafından okunabilir bir geçmişi oluşturulur.

semantic-release, bir sonraki sürümü geleneksel değişiklik kaydı iletilerinden belirleyen tamamen otomatik bir sürümleme aracıdır (feat: → küçük, fix: → yama, BREAKING CHANGE: → ana). Sürümü artırır, değişiklik günlüğünü oluşturur ve npm'e yayımlar — bunların tümü main dalıyla birleştirme sonrasında CI tarafından tetiklenir. Elle sürüm yönetimi gerekmez.

Kapsamsız paketler (my-component) her zaman geneldir. Kapsamlı paketler (@myorg/my-component) varsayılan olarak kısıtlıdır (özeldir); npm publish --access public komutuyla bunları genel olarak yayımlayabilirsiniz. Kısıtlı paketler için ücretli bir npm hesabı veya kuruluş gerekir. İlk yayımlamanızdan önce erişim ayarlarını doğrulayın.

npm kaynak doğrulaması, yayımladığınız paketi doğrulanabilir bir şekilde belirli bir git kaydına bağlar. GitHub Actions içinde npm publish --provenance komutuyla etkinleştirin. Kullanıcılar, yükledikleri paketin npm kayıt sayfasında gösterilen tam kaynak kaydından oluşturulduğunu doğrulayabilir. Bu, yazılım tedarik zinciri güvenliğini önemli ölçüde artırır.

Bir sürümde kritik bir hata veya uyumluluğu bozan bir değişiklik olduğunda onu kullanımdan kaldırın: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm, bu sürümü yükleyen herkese kullanımdan kaldırma uyarısı gösterir. Sürüm kaldırılmaz (npm, yayımlanmış sürümleri varsayılan olarak silmez); ancak kullanıcılar yükseltme yapmaları için uyarılır.

Kapsamlı paketler @scope/package-name biçimini kullanır. Kapsam genellikle npm kullanıcı adınız veya kuruluşunuzun adıdır. Kapsamlı paketler, paketi kimin sürdürdüğünü açıkça gösterir ve kapsamsız paketlerle ad çakışmalarını önler. Özel paketler ve kuruluşunuzla ilişkili açık kaynak paketler için kapsamlı paketler kullanın.

Önizleme yapmak için npm publish --dry-run komutunu, yayımlanacak içerikleri denetlemek için de dosyalar alanını kullanın. Anlamsal sürümleme: uyumluluğu bozan değişiklikler için MAJOR, yeni özellikler için MINOR, düzeltmeler için PATCH. Ön sürümlerde -alpha/-beta/-rc etiketleri kullanılır. Changesets, ortaklaşa geliştirilen kitaplıklar için sürümlemeyi ve CHANGELOG oluşturmayı otomatikleştirir. semantic-release, geleneksel değişiklik kayıtlarından yola çıkarak süreci otomatikleştirir. Tedarik zinciri güvenliği için --provenance seçeneğini etkinleştirin. Hatalı sürümleri npm deprecate komutuyla kullanımdan kaldırın.