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

यह दस्तावेज़, 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 ब्लॉग पर सबमिट किया जाएगा.