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