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