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