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

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

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

खास जानकारी

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

• अगर बदलाव की वजह से, Bazel में उपयोगकर्ताओं को दिखने वाले तरीके से कोई बदलाव होता है, तो इसके बारे में बताना फ़ायदेमंद हो सकता है.

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

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

रिलीज़ नोट हमारे उपयोगकर्ता पढ़ेंगे. इसलिए, यह कम शब्दों में (आदर्श तौर पर एक वाक्य में) होना चाहिए. इसमें तकनीकी शब्दों (Bazel की अंदरूनी शब्दावली) का इस्तेमाल नहीं किया जाना चाहिए. साथ ही, इसमें इस बात पर फ़ोकस होना चाहिए कि बदलाव किस बारे में है.

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

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

• बग के ब्यौरे को सिर्फ़ कॉपी और चिपकाएं नहीं. ये अक्सर मुश्किल होते हैं और सिर्फ़ हमें समझ में आते हैं. साथ ही, उपयोगकर्ताओं को इन्हें समझने में मुश्किल होती है. रिलीज़ नोट का मकसद, उपयोगकर्ताओं को उनकी भाषा में यह बताना है कि क्या बदला है और क्यों.

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

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

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

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

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

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

प्रोसेस

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

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

इसके बाद, bazel-blog repository का इस्तेमाल करके, सूचना को Bazel blog पर सबमिट किया जाएगा.