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