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