प्रॉडक्ट की जानकारी लिखना

यह दस्तावेज़ बेज़ेल में योगदान देने वालों के लिए है.

Baज़ल में, कमिट के बारे में जानकारी में एक RELNOTES: टैग शामिल होता है. इसके बाद, एक रिलीज़ नोट शामिल होता है. इसका इस्तेमाल Basel टीम हर रिलीज़ में बदलावों को ट्रैक करने और रिलीज़ की सूचना लिखने के लिए करती है.

खास जानकारी

• क्या आपने जो बदलाव किया है क्या उससे कोई गड़बड़ी हुई? ऐसे में, आपको रिलीज़ नोट की ज़रूरत नहीं पड़ती. कृपया GitHub की समस्या की जानकारी दें.

• अगर यह बदलाव लोगों को साफ़ तौर पर दिखता है और बेज़ल को जोड़ता / हटाता है / बदलता है, तो इसके बारे में बताने से फ़ायदा हो सकता है.

अगर बदलाव अहम है, तो सबसे पहले डिज़ाइन से जुड़ी दस्तावेज़ नीति का पालन करें.

दिशा-निर्देश

रिलीज़ नोट हमारे उपयोगकर्ता पढ़ेंगे, इसलिए इसे छोटा (आम तौर पर एक वाक्य) होना चाहिए, कठिन शब्दों (Baज़ल-इंटरनल शब्दावली) से बचें. साथ ही, उपयोगकर्ताओं को इस बात पर ध्यान देना चाहिए कि बदलाव किस बारे में है.

• सही दस्तावेज़ का लिंक शामिल करें. करीब-करीब हर रिलीज़ नोट में एक लिंक होना चाहिए. अगर जानकारी में किसी फ़्लैग, सुविधा, कमांड के नाम के बारे में बताया गया है, तो हो सकता है कि उपयोगकर्ता उसके बारे में ज़्यादा जानना चाहें.

• कोड, सिंबल, फ़्लैग या अंडरस्कोर वाले किसी भी शब्द के आस-पास बैककोट का इस्तेमाल करें.

• सिर्फ़ गड़बड़ी की जानकारी कॉपी और पेस्ट न करें. वे अक्सर छुपे रहते हैं और केवल हमें ही समझ में आते हैं और उपयोगकर्ता को अपना सिर खुजाते हैं. रिलीज़ नोट की मदद से लोगों को समझने लायक भाषा में समझा जा सकता है कि क्या बदलाव हुए हैं और क्यों.

• हमेशा वर्तमान काल और "Baज़ल अब Y का समर्थन करता है" या "X अब Z करता है" फ़ॉर्मैट का इस्तेमाल करें. हम नहीं चाहते कि हमारे रिलीज़ नोट, गड़बड़ी की एंट्री की तरह दिखें. रिलीज़ नोट की सभी एंट्री में जानकारी होनी चाहिए और उनकी स्टाइल और भाषा एक जैसी होनी चाहिए.

• अगर किसी चीज़ को रोक दिया गया है या हटा दिया गया है, तो "X को हटा दिया गया है" या "X को हटा दिया गया है" जैसे शब्दों का इस्तेमाल करें. "हटाया गया" या "हटाया गया" नहीं.

• अगर Basel अब कुछ अलग तरीके से करता है, तो वर्तमान काल में "$oldBehavior की बजाय X अब $newBehavior" इस्तेमाल करें." इससे उपयोगकर्ता को पूरी जानकारी मिलती है कि नई रिलीज़ का इस्तेमाल करते समय क्या होगा.

• अगर Basel अब किसी चीज़ के साथ काम करता है या अब नहीं करता है, तो "Basel अब X के साथ काम करता है / अब X के साथ काम नहीं करता है" का इस्तेमाल करें.

• इस बारे में जानकारी दें कि क्यों कुछ हटा दिया गया है / काम नहीं कर रहा है / उसमें बदलाव क्यों किया गया है. एक वाक्य काफ़ी है, लेकिन हम चाहते हैं कि उपयोगकर्ता अपने बिल्ड पर पड़ने वाले असर का आकलन कर सकें.

• आने वाले समय में मिलने वाले फ़ंक्शन के बारे में कोई वादा न करें. "इस फ़्लैग को हटा दिया जाएगा" या "इसे बदल दिया जाएगा" जैसे शब्दों से बचें. इसकी वजह से अनिश्चितता होती है. उपयोगकर्ता को सबसे पहले यह सोचना होगा कि "कब?"

प्रोसेस

रिलीज़ की प्रोसेस के तहत, हम हर बदलाव के लिए RELNOTES टैग इकट्ठा करते हैं. हम उस Google दस्तावेज़ में मौजूद सभी चीज़ों को कॉपी करते हैं जहां हम नोट की समीक्षा करते हैं, उनमें बदलाव करते हैं, और उन्हें व्यवस्थित करते हैं.

रिलीज़ मैनेजर, bazel-dev के ईमेल पाने वाले लोगों की सूची को एक ईमेल भेजता है. बेज़ल योगदान देने वालों को दस्तावेज़ में योगदान देने का न्योता दिया जाता है, ताकि वे यह पक्का कर सकें कि उनके किए गए बदलाव सूचना में सही तरीके से दिखें.

बाद में, इस सूचना को Bazz ब्लॉग पर सबमिट किया जाएगा. ऐसा करने के लिए, bazz-blog डेटा स्टोर करने की जगह का इस्तेमाल किया जाएगा.