GitHub रिलीज़

githubReleases() स्रोत के साथ किसी रिपॉज़िटरी की GitHub रिलीज़ को चेंजलॉग प्रविष्टियों में बदलें, ताकि आपके रिलीज़ नोट्स ही आपका चेंजलॉग बन जाएँ।

बिल्ट-इन githubReleases() एडैप्टर किसी रिपॉज़िटरी की रिलीज़ को चेंजलॉग में बदल देता है। प्रत्येक रिलीज़ एक type: changelog प्रविष्टि बन जाती है, इसलिए आपके रिलीज़ नोट्स ही आपका चेंजलॉग हैं — आपको कुछ भी दो बार लिखने की आवश्यकता नहीं है। जनरेट की गई चेंजलॉग टाइमलाइन के साथ इसका उपयोग करने पर, GitHub रिलीज़ प्रकाशित करते ही एक चेंजलॉग प्रविष्टि भी प्रकाशित हो जाती है।

import { defineConfig } from "blume";
import { filesystem, githubReleases } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "content" }),
      githubReleases({
        prefix: "changelog",
        owner: "acme",
        repo: "sdk",
        // prereleases: false,  // include prereleases (default off)
        // drafts: false,       // include drafts (needs a write token)
        // limit: 100,          // cap releases, newest-first
        // baseUrl: "https://github.acme.com/api/v3", // GitHub Enterprise Server
      }),
    ],
  },
});

प्रत्येक रिलीज़ अपने-आप चेंजलॉग फ़ील्ड्स से मैप हो जाती है। उसका नाम (या टैग) शीर्षक बनता है और उसकी प्रकाशन तिथि से टाइमलाइन का क्रम तय होता है। टैग changelog.version बनता है और प्रीरिलीज़ को Prerelease टैग दिया जाता है, ड्राफ़्ट को (जब drafts उन्हें शामिल करता है) Draft और बाकी रिलीज़ को Release। ड्राफ़्ट भी किसी अन्य रिलीज़ की तरह ही प्रकाशित होता है, इसलिए ड्राफ़्ट केवल ऐसे बिल्ड में शामिल करें जिसे पाठक नहीं देखते। नोट्स का सारांश पेज का मेटा विवरण बनता है, और चेंजलॉग का RSS फ़ीड भी इसी को आइटम के विवरण के रूप में उपयोग करता है। नोट्स प्रविष्टि के मुख्य भाग के रूप में रेंडर होते हैं और उनके लिंक्स में दो बदलाव किए जाते हैं। पहला, जो लिंक वेब, मेल, फ़ोन या सापेक्ष पता नहीं है (जैसे कोई javascript: URL), उसका केवल लेबल रखा जाता है। दूसरा, आपकी अपनी deployment.site पर जाने वाले लिंक को उसके रूट-सापेक्ष पथ में बदल दिया जाता है। इससे वह लिंक प्रीव्यू डिप्लॉय और आपके डिप्लॉयमेंट बेस के साथ सही ढंग से काम करता है। स्रोत को एक prefix दें, ताकि उसके रिलीज़ पेज /changelog/v1-2-0 जैसे रूट के अंतर्गत नेस्ट हों। /changelog पर स्थित टाइमलाइन अपना शीर्षक और विवरण स्रोत से नहीं, बल्कि शीर्ष-स्तरीय changelog कॉन्फ़िग से लेती है:

changelog: {
  title: "SDK releases",
  description: "Every release of the Acme SDK, from GitHub.",
},

निजी रिपॉज़िटरी GITHUB_TOKEN एनवायरनमेंट वेरिएबल के माध्यम से प्रमाणीकृत होती है। यह वही टोकन है जिसका उपयोग अन्य GitHub सुविधाएँ करती हैं, और इसे कभी भी आपके कॉन्फ़िग में सीधे नहीं लिखा जाता। एडैप्टर इस वेरिएबल को घोषित करता है, इसलिए इसके बिना बिल्ड करने पर चेतावनी दिखाई जाती है। GitHub Enterprise Server पर स्थित रिपॉज़िटरी के लिए, baseUrl को उसके REST API (https://<host>/api/v3) पर सेट करें। GITHUB_TOKEN वहीं भेजा जाता है, इसलिए यह उसी सर्वर का टोकन होना चाहिए। हर रिमोट स्रोत की तरह, इसे भी .blume/cache/<source>/ के अंतर्गत कैश किया जाता है। API उपलब्ध न होने पर इसे ऑफ़लाइन कैश से परोसा जाता है। चेंजलॉग एक पूरक सामग्री है, इसलिए फ़ेच विफल होने पर बिल्ड विफल नहीं होता, भले ही कोई कैश मौजूद न हो (जैसे बिना टोकन वाला CI बिल्ड)। ऐसे में चेतावनी के साथ एक खाली चेंजलॉग बनता है। चेंजलॉग में सामग्री लाने के लिए अपने CI और डिप्लॉय एनवायरनमेंट में GITHUB_TOKEN सेट करें।

GitHub रिलीज़ को प्रोडक्ट चेंजलॉग में बदलें गाइड में इसकी पूरी प्रक्रिया शुरू से अंत तक समझाई गई है। इसमें एक चेंजलॉग टाइमलाइन, प्रत्येक रिलीज़ के लिए एक पेज और एक RSS फ़ीड शामिल है। जब भी आप कोई रिलीज़ प्रकाशित करते हैं, ये सभी फिर से बिल्ड हो जाते हैं।