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

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