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