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

Nightly · 9.1 · 9.0 · 8.7 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

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

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

खास जानकारी

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

  • अगर बदलाव की वजह से, Bazel में कोई सुविधा जोड़ी जाती है, हटाई जाती है या उसमें बदलाव किया जाता है, तो इसके बारे में बताया जा सकता है.

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

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

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

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

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

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

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

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

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

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

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

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

प्रोसेस

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

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

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