अगर आपको उपयोगकर्ता के लिए कोई नई सुविधा जोड़नी है, उसमें बदलाव करना है या उसे हटाना है या Bazel में आर्किटेक्चर से जुड़ा कोई अहम बदलाव करना है, तो आपको बदलाव सबमिट करने से पहले, डिज़ाइन से जुड़ा दस्तावेज़ लिखना होगा और उसकी समीक्षा करवानी होगी.
यहां कुछ अहम बदलावों के उदाहरण दिए गए हैं:
- नेटिव बिल्ड के नियमों को जोड़ना या हटाना
- नेटिव नियमों में ऐसे बदलाव करना जिनसे मौजूदा सिस्टम पर असर पड़े
- नेटिव बिल्ड के किसी ऐसे नियम के सिमैंटिक्स में बदलाव करना जिससे एक से ज़्यादा नियमों के व्यवहार पर असर पड़े
- Bazel के नियम की परिभाषा वाले एपीआई में बदलाव करना
- Bazel, अन्य सिस्टम से कनेक्ट होने के लिए जिन एपीआई का इस्तेमाल करता है उनमें बदलाव करना
- Starlark भाषा, सिमैंटिक्स या एपीआई में बदलाव करना
- ऐसे बदलाव करना जिनसे Bazel की परफ़ॉर्मेंस या मेमोरी के इस्तेमाल पर व्यापक असर पड़ सकता है (चाहे अच्छा हो या बुरा)
- बड़े पैमाने पर इस्तेमाल किए जाने वाले इंटरनल एपीआई में बदलाव करना
- फ़्लैग और कमांड-लाइन इंटरफ़ेस में बदलाव करना.
डिज़ाइन की समीक्षा करने की वजहें
डिज़ाइन से जुड़ा दस्तावेज़ लिखते समय, Bazel के अन्य डेवलपर के साथ मिलकर काम किया जा सकता है. साथ ही, Bazel की कोर टीम से सलाह ली जा सकती है. उदाहरण के लिए, अगर किसी सुझाव से जोड़ा जाता है, हटाया जाता है या BUILD, MODULE.bazel या 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 के किसी मैनेजर को फिर से असाइन करें.
समीक्षा की प्रोसेस के दौरान
- पक्का करें कि टिप्पणी और डिज़ाइन में बदलाव करने की प्रोसेस, सही तरीके से आगे बढ़े.
- मंज़ूरी देने से पहले, पक्का करें कि अन्य समीक्षकों की समस्याएं हल हो गई हों.
सभी समीक्षकों की मंज़ूरी मिलने के बाद
- पक्का करें कि मेलिंग सूची पर सूचना दिए जाने के बाद, कम से कम एक हफ़्ता बीत चुका हो.
- पक्का करें कि पीआर, स्थिति को अपडेट करे.
- सुझाव के लेखक की ओर से भेजे गए पीआर को मंज़ूरी दें.
डिज़ाइन अस्वीकार करना
- पक्का करें कि पीआर का लेखक, पीआर भेजे. इसके अलावा, उसे पीआर भेजा जा सकता है.
- पीआर, दस्तावेज़ की स्थिति को अपडेट करता है.
- दस्तावेज़ में एक टिप्पणी जोड़ें. इसमें बताएं कि मौजूदा स्थिति में डिज़ाइन को मंज़ूरी क्यों नहीं दी जा सकती. साथ ही, अगले चरणों के बारे में बताएं. जैसे, "गलत मान्यताओं पर फिर से विचार करें और फिर से सबमिट करें".