यह दस्तावेज़, Bazel में योगदान देने वाले लोगों के लिए है.
Bazel में कमिट के ब्यौरे में, RELNOTES: टैग के बाद रिलीज़ नोट शामिल होता है. Bazel टीम इसका इस्तेमाल, हर रिलीज़ में हुए बदलावों को ट्रैक करने और रिलीज़ का एलान करने के लिए करती है.
खास जानकारी
क्या आपका बदलाव, गड़बड़ी को ठीक करने के लिए किया गया है? ऐसे में, आपको रिलीज़ नोट की ज़रूरत नहीं है. कृपया GitHub पर मौजूद समस्या का रेफ़रंस शामिल करें.
अगर बदलाव से, उपयोगकर्ता को दिखने वाले तरीके से Bazel को जोड़ा / हटाया / बदला जाता है, तो इसके बारे में बताना फ़ायदेमंद हो सकता है.
अगर बदलाव ज़रूरी है, तो पहले डिज़ाइन दस्तावेज़ से जुड़ी नीति का पालन करें.
दिशा-निर्देश
रिलीज़ नोट को हमारे उपयोगकर्ता पढ़ेंगे. इसलिए, यह छोटा होना चाहिए (आदर्श रूप से एक वाक्य). इसमें, ज़्यादा जानकारी देने वाले शब्दों (Bazel के अंदर इस्तेमाल होने वाले शब्द) का इस्तेमाल नहीं करना चाहिए. साथ ही, इसमें इस बात पर फ़ोकस करना चाहिए कि बदलाव किस बारे में है.
ज़रूरी दस्तावेज़ का लिंक शामिल करें. किसी भी रिलीज़ नोट में लिंक होना चाहिए. अगर ब्यौरे में किसी फ़्लैग, सुविधा या कमांड के नाम के बारे में बताया गया है, तो हो सकता है कि उपयोगकर्ता इसके बारे में ज़्यादा जानना चाहें.
कोड, सिंबल, फ़्लैग या अंडरस्कोर वाले किसी भी शब्द के चारों ओर बैककोट का इस्तेमाल करें.
गड़बड़ी की जानकारी को सिर्फ़ कॉपी करके चिपकाएं. ये अक्सर ऐसे होते हैं जिनका मतलब सिर्फ़ हम समझ पाते हैं और उपयोगकर्ता को समझ नहीं आता. रिलीज़ नोट में, उपयोगकर्ताओं के हिसाब से आसान भाषा में यह बताया जाता है कि क्या बदलाव किया गया है और क्यों किया गया है.
हमेशा मौजूदा समय और "Bazel अब Y के साथ काम करता है" या "X अब Z के साथ काम करता है" फ़ॉर्मैट का इस्तेमाल करें. हम नहीं चाहते कि रिलीज़ नोट, गड़बड़ी की जानकारी देने वाले नोट की तरह लगें. रिलीज़ नोट की सभी एंट्री में जानकारी होनी चाहिए. साथ ही, एक जैसी स्टाइल और भाषा का इस्तेमाल किया जाना चाहिए.
अगर किसी सुविधा को बंद कर दिया गया है या हटा दिया गया है, तो "X को बंद कर दिया गया है" या "X को हटा दिया गया है" का इस्तेमाल करें. "हटाया गया" या "हटाया गया था" नहीं.
अगर Bazel अब कुछ अलग तरीके से काम करता है, तो "X अब $oldBehavior के बजाय $newBehavior का इस्तेमाल करता है" का इस्तेमाल करें. इससे उपयोगकर्ता को यह जानकारी मिलती है कि नई रिलीज़ का इस्तेमाल करने पर, उन्हें क्या उम्मीद करनी चाहिए.
अगर Bazel अब किसी सुविधा के साथ काम करता है या नहीं करता है, तो "Bazel अब X के साथ काम करता है/नहीं करता है" का इस्तेमाल करें.
बताएं कि किसी चीज़ को क्यों हटाया गया है / उसे बंद क्यों किया गया है / उसमें बदलाव क्यों किया गया है. एक वाक्य काफ़ी है, लेकिन हम चाहते हैं कि उपयोगकर्ता अपने बिल्ड पर पड़ने वाले असर का आकलन कर सके.
आने वाले समय में मिलने वाले फ़ंक्शन के बारे में कोई वादा न करें. "यह फ़्लैग हटा दिया जाएगा" या "इसमें बदलाव किया जाएगा" जैसे वाक्यों का इस्तेमाल न करें. इससे अनिश्चितता पैदा होती है. उपयोगकर्ता सबसे पहले यह जानना चाहेगा कि "कब?" और हम नहीं चाहते कि वह किसी अनजान समय पर, अपने मौजूदा बिल्ड के काम न करने की चिंता करे.
प्रोसेस
रिलीज़ की प्रोसेस के तहत, हम हर कमिट के RELNOTES टैग इकट्ठा करते हैं. हम सभी जानकारी को Google Docs में कॉपी करते हैं. इसके बाद, हम नोट की समीक्षा करते हैं, उनमें बदलाव करते हैं, और उन्हें व्यवस्थित करते हैं.
रिलीज़ मैनेजर, bazel-dev की मेलिंग-लिस्ट पर एक ईमेल भेजता है. Bazel के योगदान देने वालों को दस्तावेज़ में योगदान देने का न्योता दिया गया है. साथ ही, यह पक्का करने के लिए कहा गया है कि उनके बदलाव, एलान में सही तरीके से दिखें.
बाद में, bazel-blog रिपॉज़िटरी का इस्तेमाल करके, Bazel के ब्लॉग पर यह एलान सबमिट किया जाएगा.