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