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