अगर आपको उपयोगकर्ताओं के लिए कोई सुविधा जोड़नी है, उसमें बदलाव करना है या उसे हटाना है या Bazel में आर्किटेक्चर में कोई बड़ा बदलाव करना है, तो आपको बदलाव सबमिट करने से पहले, डिज़ाइन दस्तावेज़ लिखना होगा और उसकी समीक्षा करनी होगी.
यहां कुछ अहम बदलावों के उदाहरण दिए गए हैं:
- नेटिव बिल्ड नियमों को जोड़ना या मिटाना
- नेटिव नियमों में होने वाले बदलाव
- नेटिव बिल्ड नियम के सेमेंटेक्स में बदलाव, जो एक से ज़्यादा नियमों के व्यवहार पर असर डालते हैं
- Bazel के नियम की परिभाषा वाले एपीआई में बदलाव
- उन एपीआई में बदलाव जिनका इस्तेमाल Bazel, दूसरे सिस्टम से कनेक्ट करने के लिए करता है
- Starlark भाषा, सेमेटिक्स या एपीआई में बदलाव
- ऐसे बदलाव जिनका असर Bazel की परफ़ॉर्मेंस या मेमोरी के इस्तेमाल पर पड़ सकता है (बेहतर या खराब)
- आम तौर पर इस्तेमाल किए जाने वाले इंटरनल एपीआई में बदलाव
- फ़्लैग और कमांड-लाइन इंटरफ़ेस में बदलाव.
डिज़ाइन की समीक्षाओं की वजहें
डिज़ाइन दस्तावेज़ लिखते समय, Bazel के अन्य डेवलपर के साथ मिलकर काम किया जा सकता है और Bazel की मुख्य टीम से सलाह ली जा सकती है. उदाहरण के लिए, जब कोई प्रस्ताव, BUILD, MODULE.bazel या bzl फ़ाइलों में मौजूद किसी फ़ंक्शन या ऑब्जेक्ट को जोड़ता है, हटाता है या उसमें बदलाव करता है, तो समीक्षकों के तौर पर Starlark टीम को जोड़ें. डिज़ाइन के दस्तावेज़ों की समीक्षा सबमिट करने से पहले की जाती है, क्योंकि:
- Bazel एक बहुत ही जटिल सिस्टम है. ऐसा हो सकता है कि स्थानीय तौर पर किए गए छोटे-मोटे बदलावों से, दुनिया भर में काफ़ी असर पड़े.
- टीम को उपयोगकर्ताओं से, सुविधाओं के कई अनुरोध मिलते हैं. ऐसे अनुरोधों का आकलन, सिर्फ़ तकनीकी संभवता के लिए नहीं, बल्कि अन्य सुविधाओं के अनुरोधों के हिसाब से भी किया जाना चाहिए.
- Bazel की सुविधाओं को अक्सर मुख्य टीम के बाहर के लोग लागू करते हैं. इन योगदान देने वालों के पास Bazel के बारे में अलग-अलग लेवल की विशेषज्ञता होती है.
- Bazel टीम के अलग-अलग सदस्यों के पास अलग-अलग लेवल की विशेषज्ञता होती है. टीम के किसी भी सदस्य को Bazel के हर पहलू की पूरी जानकारी नहीं होती.
- Bazel में किए गए बदलावों को पुराने सिस्टम के साथ काम करने की सुविधा के हिसाब से बनाया जाना चाहिए. साथ ही, ऐसे बदलाव नहीं होने चाहिए जिनसे कोई समस्या पैदा हो.
Bazel की डिज़ाइन की समीक्षा करने की नीति से, इन चीज़ों की संभावना बढ़ जाती है:
- सुविधाओं के सभी अनुरोधों की जांच की जाती है.
- हम किसी ऐसे तरीके को लागू करने में समय और पैसा नहीं लगाएंगे जो काम न करे. इसके बजाय, हम सही लोगों की मदद से डिज़ाइन पर काम करेंगे.
शुरू करने में मदद पाने के लिए, Bazel के प्रस्तावों के रिपॉज़िटरी में डिज़ाइन दस्तावेज़ देखें. डिज़ाइन पर लगातार काम किया जा रहा है. इसलिए, समय के साथ और सुझाव/राय के आधार पर, लागू करने की जानकारी में बदलाव हो सकते हैं. पब्लिश किए गए डिज़ाइन दस्तावेज़ों में, डिज़ाइन लागू होने के दौरान किए गए बदलावों के बजाय, डिज़ाइन का शुरुआती वर्शन कैप्चर होता है. Bazel की मौजूदा सुविधाओं के बारे में जानकारी पाने के लिए, हमेशा दस्तावेज़ देखें.
योगदान देने वाले का वर्कफ़्लो
योगदान देने वाले के तौर पर, आपके पास डिज़ाइन दस्तावेज़ लिखने, पुश अनुरोध भेजने, और अपने प्रस्ताव के लिए समीक्षकों से अनुरोध करने का विकल्प होता है.
डिज़ाइन दस्तावेज़ लिखना
सभी डिज़ाइन दस्तावेज़ों में हेडर होना चाहिए. इसमें ये चीज़ें शामिल होनी चाहिए:
- लेखक
- आखिरी बड़े बदलाव की तारीख
- समीक्षकों की सूची, जिसमें एक (और सिर्फ़ एक) मुख्य समीक्षक शामिल हो
- मौजूदा स्थिति (ड्राफ़्ट, समीक्षा में है, स्वीकार किया गया, अस्वीकार किया गया, लागू किया जा रहा है, लागू किया गया)
- चर्चा के थ्रेड का लिंक (घोषणा के बाद जोड़ा जाएगा)
दस्तावेज़ को सभी के लिए उपलब्ध Google दस्तावेज़ के तौर पर लिखा जा सकता है या मार्कडाउन का इस्तेमाल करके लिखा जा सकता है. Markdown / Google Docs की तुलना करने के बारे में नीचे पढ़ें.
जिन बदलावों का असर उपयोगकर्ताओं पर पड़ता है उनके लिए, पुराने सिस्टम के साथ काम करने की सुविधा पर पड़ने वाले असर के बारे में जानकारी देने वाला सेक्शन होना चाहिए. साथ ही, ज़रूरत पड़ने पर रोल आउट का प्लान भी होना चाहिए.
पुल का अनुरोध करना
डिज़ाइन इंडेक्स में दस्तावेज़ जोड़ने के लिए, पुश रिक्वेस्ट (पीआर) बनाकर अपना डिज़ाइन दस्तावेज़ शेयर करें. अपने पीआर में मार्कडाउन फ़ाइल या दस्तावेज़ का लिंक जोड़ें.
अगर हो सके, तो समीक्षा करने वाले किसी व्यक्ति को चुनें. साथ ही, समीक्षा करने वाले अन्य लोगों को कॉपी भेजें. अगर आपने मुख्य समीक्षक नहीं चुना है, तो Bazel का रखरखाव करने वाला कोई व्यक्ति आपके पीआर के लिए एक समीक्षक असाइन करेगा.
पीआर बनाने के बाद, समीक्षक कोड की समीक्षा के दौरान शुरुआती टिप्पणियां कर सकते हैं. उदाहरण के लिए, मुख्य समीक्षक, अन्य समीक्षकों का सुझाव दे सकता है या जानकारी मौजूद न होने की ओर इशारा कर सकता है. जब लीड समीक्षक को लगता है कि समीक्षा की प्रोसेस शुरू की जा सकती है, तब वह पीआर को मंज़ूरी देता है. इसका मतलब यह नहीं है कि प्रस्ताव सही है या उसे मंज़ूरी मिल जाएगी. इसका मतलब है कि प्रस्ताव में चर्चा शुरू करने के लिए ज़रूरी जानकारी मौजूद है.
नए प्रस्ताव का एलान करना
पीआर सबमिट होने पर, bazel-dev को सूचना भेजें.
Bazel के असली उपयोगकर्ताओं से सुझाव, राय या शिकायतें पाने के लिए, bazel-discuss जैसे अन्य ग्रुप को कॉपी किया जा सकता है.
समीक्षकों के साथ फिर से अपनी रणनीति का इस्तेमाल करना
जिन लोगों में दिलचस्पी है वे आपके प्रस्ताव पर टिप्पणी कर सकते हैं. सवालों के जवाब दें, प्रपोज़ल के बारे में साफ़ तौर पर बताएं, और समस्याओं को हल करें.
चर्चा, एलान वाले थ्रेड पर होनी चाहिए. अगर प्रस्ताव किसी Google दस्तावेज़ में है, तो इसके बजाय टिप्पणियों का इस्तेमाल किया जा सकता है. ध्यान दें कि पहचान छिपाकर टिप्पणी करने की अनुमति है.
स्थिति अपडेट करना
जब बदलाव पूरा हो जाए, तो प्रस्ताव की स्थिति अपडेट करने के लिए नया पीआर बनाएं. प्रॉडक्ट रिलीज़ को उसी मुख्य समीक्षक को भेजें और दूसरे समीक्षकों को कॉपी भेजें.
प्रपोज़ल को आधिकारिक तौर पर स्वीकार करने के लिए, मुख्य समीक्षक यह पक्का करने के बाद पीआर को मंज़ूरी देता है कि अन्य समीक्षक इस फ़ैसले से सहमत हैं.
पहले एलान और किसी प्रस्ताव को मंज़ूरी मिलने के बीच कम से कम एक हफ़्ता का अंतर होना चाहिए. इससे यह पक्का होता है कि उपयोगकर्ताओं के पास दस्तावेज़ को पढ़ने और अपनी समस्याओं को शेयर करने के लिए ज़रूरत के मुताबिक समय था.
प्रस्ताव स्वीकार किए जाने से पहले ही, उसे लागू किया जा सकता है. उदाहरण के लिए, कॉन्सेप्ट की पुष्टि करने या प्रयोग के तौर पर. हालांकि, समीक्षा पूरी होने से पहले बदलाव सबमिट नहीं किया जा सकता.
मुख्य समीक्षक चुनना
लीड समीक्षक, डोमेन का विशेषज्ञ होना चाहिए. साथ ही, वह:
- काम के सबसिस्टम के बारे में जानकारी
- मकसद के हिसाब से और काम के सुझाव देने में सक्षम
- समीक्षा की पूरी अवधि के दौरान, समीक्षा की प्रक्रिया को पूरा करने के लिए उपलब्ध होना चाहिए
अलग-अलग टीम लेबल के लिए संपर्क देखें.
Markdown बनाम Google Docs
यह तय करें कि आपके लिए कौनसा विकल्प सबसे अच्छा है, क्योंकि दोनों को स्वीकार किया जाता है.
Google Docs का इस्तेमाल करने के फ़ायदे:
- यह ब्रेनस्टॉर्मिंग के लिए असरदार है, क्योंकि इसका इस्तेमाल करना आसान है.
- साथ मिलकर बदलाव करना.
- तेज़ी से विज्ञापन के अलग-अलग वर्शन बनाना.
- बदलावों का सुझाव देने का आसान तरीका.
Markdown फ़ाइलों का इस्तेमाल करने के फ़ायदे:
- लिंक करने के लिए छोटे किए गए यूआरएल.
- बदलावों का साफ़ तौर पर रिकॉर्ड.
- लिंक को सार्वजनिक करने से पहले, ऐक्सेस के अधिकार सेट अप करना न भूलें.
- सर्च इंजन की मदद से आसानी से खोजा जा सकता है.
- आने वाले समय में भी काम आता है: प्लैन टेक्स्ट को किसी खास टूल की ज़रूरत नहीं होती और इसके लिए इंटरनेट कनेक्शन की ज़रूरत भी नहीं होती.
- लेखक के मौजूद न होने पर भी, उन्हें अपडेट किया जा सकता है.
- इनकी प्रोसेस अपने-आप की जा सकती है. जैसे, काम न करने वाले लिंक अपडेट करना/उनका पता लगाना, लेखकों की सूची फ़ेच करना वगैरह.
पहले Google दस्तावेज़ पर बार-बार इस्तेमाल होने वाले टेक्स्ट को चुनें और फिर उसे बाद में इस्तेमाल करने के लिए, मार्कडाउन में बदलें.
Google Docs का इस्तेमाल करना
एक जैसा दस्तावेज़ बनाने के लिए, Bazel डिज़ाइन दस्तावेज़ टेंप्लेट का इस्तेमाल करें. इसमें ज़रूरी हेडर शामिल होता है और Bazel से जुड़े अन्य दस्तावेज़ों के साथ विज़ुअल एक जैसा दिखता है. ऐसा करने के लिए, फ़ाइल > कॉपी बनाएं पर क्लिक करें. इसके अलावा, डिज़ाइन दस्तावेज़ टेंप्लेट की कॉपी बनाने के लिए, इस लिंक पर क्लिक करें.
अपने दस्तावेज़ को सभी के लिए पढ़ने लायक बनाने के लिए, शेयर करें > बेहतर > बदलें… पर क्लिक करें. इसके बाद, "चालू है - जिनके पास लिंक है वे सभी" चुनें. अगर आपने दस्तावेज़ पर टिप्पणी करने की अनुमति दी है, तो कोई भी व्यक्ति बिना Google खाते के भी टिप्पणी कर सकता है.
Markdown का इस्तेमाल करना
दस्तावेज़, GitHub पर सेव किए जाते हैं और इनमें GitHub फ़्लेवर का Markdown (स्पेसिफ़िकेशन) इस्तेमाल किया जाता है.
किसी मौजूदा दस्तावेज़ को अपडेट करने के लिए, एक पीआर बनाएं. अहम बदलावों की समीक्षा, दस्तावेज़ की समीक्षा करने वाले लोगों को करनी चाहिए. छोटी-मोटी गड़बड़ियों (जैसे, टाइपिंग की गड़बड़ियां, फ़ॉर्मैटिंग) को कोई भी व्यक्ति ठीक कर सकता है.
समीक्षक का वर्कफ़्लो
समीक्षक, डिज़ाइन दस्तावेज़ों पर टिप्पणी करता है, उनकी समीक्षा करता है, और उन्हें मंज़ूरी देता है.
समीक्षक की सामान्य ज़िम्मेदारियां
डिज़ाइन के दस्तावेज़ों की समीक्षा करने, ज़रूरत पड़ने पर ज़्यादा जानकारी मांगने, और समीक्षा की प्रक्रिया को पूरा करने वाले डिज़ाइन को मंज़ूरी देने की ज़िम्मेदारी आपकी है.
जब आपको कोई नया प्रस्ताव मिले
- दस्तावेज़ को एक नज़र देखें.
- अगर कोई ज़रूरी जानकारी मौजूद नहीं है या डिज़ाइन, प्रोजेक्ट के लक्ष्यों के मुताबिक नहीं है, तो टिप्पणी करें.
- समीक्षा करने के लिए अन्य लोगों के नाम सुझाएं.
- जब वह समीक्षा के लिए तैयार हो, तब उसे मंज़ूरी दें.
समीक्षा की प्रोसेस के दौरान
- डिज़ाइन के लेखक से उन समस्याओं के बारे में बातचीत करें जिनमें समस्या है या जिनके बारे में आपको जानकारी चाहिए.
- अगर ज़रूरी हो, तो उन लोगों से टिप्पणी करने का अनुरोध करें जिन्होंने डिज़ाइन की समीक्षा नहीं की है, लेकिन उन्हें डिज़ाइन के बारे में पता होना चाहिए.
- यह तय करें कि अनुमति पाने के लिए, लेखक को किन टिप्पणियों का जवाब देना होगा.
- अगर आपको प्रस्ताव की मौजूदा स्थिति से संतुष्टि है, तो बातचीत की थ्रेड में "LGTM" (मुझे ठीक लग रहा है) लिखें.
डिज़ाइन की समीक्षा के सभी अनुरोधों के लिए, यह प्रोसेस अपनाएं. अगर डिज़ाइन, डिज़ाइन इंडेक्स में शामिल नहीं हैं, तो उन डिज़ाइन को अनुमति न दें जिनसे Bazel पर असर पड़ता है.
मुख्य समीक्षक की ज़िम्मेदारियां
किसी डिज़ाइन को लागू करने के लिए, 'जारी करें' या 'जारी न करें' का फ़ैसला लेने की ज़िम्मेदारी आपकी है. अगर ऐसा नहीं किया जा सकता, तो आपको किसी ऐसे व्यक्ति को चुनना चाहिए जो इस काम को कर सके. इसके लिए, पीआर को उस व्यक्ति को फिर से असाइन करें या गड़बड़ी को किसी ऐसे Bazel मैनेजर को फिर से असाइन करें जो आगे की कार्रवाई कर सके.
समीक्षा की प्रोसेस के दौरान
- पक्का करें कि टिप्पणी और डिज़ाइन में बदलाव करने की प्रोसेस, सही दिशा में आगे बढ़े.
- अनुमति देने से पहले, पक्का करें कि समीक्षकों की बताई गई समस्याएं हल हो गई हों.
सभी समीक्षकों की मंज़ूरी मिलने के बाद
- पक्का करें कि मेलिंग सूची में सूचना देने के बाद, कम से कम एक हफ़्ता बीत गया हो.
- पक्का करें कि पीआर से स्थिति अपडेट हो गई हो.
- प्रपोज़ल के लेखक से मिले पीआर को स्वीकार करें.
डिज़ाइन अस्वीकार करना
- पक्का करें कि पीआर का लेखक पीआर भेजे या आप उसे पीआर भेजें.
- पीआर, दस्तावेज़ की स्थिति को अपडेट करता है.
- दस्तावेज़ में एक टिप्पणी जोड़ें, जिसमें यह बताया गया हो कि डिज़ाइन को मौजूदा स्थिति में मंज़ूरी क्यों नहीं दी जा सकती. साथ ही, अगर कोई अगला चरण है, तो उसके बारे में भी बताएं. जैसे, "अमान्य अनुमान पर फिर से जाएं और फिर से सबमिट करें".