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

Nightly · 9.1 · 9.0 · 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 अब किसी काम को अलग तरीके से करता है, तो वर्तमान काल में "$oldBehavior" के बजाय "X now $newBehavior" का इस्तेमाल करें. इससे उपयोगकर्ता को यह पता चलता है कि नई रिलीज़ का इस्तेमाल करने पर उन्हें क्या मिलेगा.

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

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

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

प्रोसेस

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

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

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