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

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

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

खास जानकारी

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

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

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

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

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

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

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

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

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

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

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

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

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

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

प्रोसेस

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

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

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