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