डिज़ाइन दस्तावेज़

अगर आपको उपयोगकर्ता के लिए दिखने वाली कोई सुविधा जोड़नी, बदलनी या हटानी है या Bazel में आर्किटेक्चर से जुड़ा कोई अहम बदलाव करना है, तो आपको बदलाव सबमिट करने से पहले, डिज़ाइन से जुड़ा दस्तावेज़ लिखना होगा और उसकी समीक्षा करानी होगी.

यहां अहम बदलावों के कुछ उदाहरण दिए गए हैं:

• नेटिव बिल्ड के नियमों को जोड़ना या हटाना
• नेटिव नियमों में ऐसे बदलाव करना जिनसे मौजूदा सिस्टम पर असर पड़ता है
• नेटिव बिल्ड के किसी ऐसे नियम के सिमैंटिक में बदलाव करना जिससे एक से ज़्यादा नियमों के व्यवहार पर असर पड़ता है
• Bazel के नियम की परिभाषा वाले एपीआई में बदलाव करना
• Bazel के उन एपीआई में बदलाव करना जिनका इस्तेमाल वह दूसरे सिस्टम से कनेक्ट करने के लिए करता है
• Starlark भाषा, सिमैंटिक या एपीआई में बदलाव करना
• ऐसे बदलाव करना जिनसे Bazel की परफ़ॉर्मेंस या मेमोरी के इस्तेमाल पर व्यापक असर पड़ सकता है (चाहे वह बेहतर हो या खराब)
• आम तौर पर इस्तेमाल किए जाने वाले इंटरनल एपीआई में बदलाव करना
• फ़्लैग और कमांड-लाइन इंटरफ़ेस में बदलाव करना.

डिज़ाइन की समीक्षा करने की वजहें

डिज़ाइन से जुड़ा दस्तावेज़ लिखते समय, Bazel के अन्य डेवलपर के साथ मिलकर काम किया जा सकता है. साथ ही, Bazel की कोर टीम से सलाह ली जा सकती है. उदाहरण के लिए, अगर किसी प्रस्ताव में किसी फ़ंक्शन या ऑब्जेक्ट को जोड़ा जाता है, हटाया जाता है या बदला जाता है, जो BUILD, MODULE.bazel या bzl फ़ाइलों में उपलब्ध है, तो Starlark टीम को समीक्षक के तौर पर शामिल करें. डिज़ाइन से जुड़े दस्तावेज़ों की समीक्षा, उन्हें सबमिट करने से पहले की जाती है. इसकी वजहें यहां दी गई हैं:

• Bazel एक बहुत ही जटिल सिस्टम है. स्थानीय स्तर पर किए गए छोटे-मोटे बदलावों से भी, दुनिया भर में अहम असर पड़ सकता है.
• टीम को उपयोगकर्ताओं से सुविधाओं के लिए कई अनुरोध मिलते हैं. इन अनुरोधों का आकलन, तकनीकी तौर पर मुमकिन होने के साथ-साथ अन्य अनुरोधों के मुकाबले उनकी अहमियत के आधार पर भी किया जाता है.
• Bazel की सुविधाओं को अक्सर कोर टीम के बाहर के लोग लागू करते हैं. ऐसे योगदानकर्ताओं के पास Bazel के बारे में अलग-अलग लेवल का अनुभव होता है.
• Bazel टीम के सदस्यों के पास भी अलग-अलग लेवल का अनुभव होता है. टीम का कोई भी सदस्य, Bazel के हर पहलू को पूरी तरह नहीं समझता.
• Bazel में किए जाने वाले बदलाव, पुराने सिस्टम के साथ काम करने वाले होने चाहिए. साथ ही, ऐसे बदलाव नहीं किए जाने चाहिए जिनसे मौजूदा सिस्टम पर असर पड़ता हो.

Bazel की डिज़ाइन की समीक्षा करने की नीति से, इस बात की संभावना बढ़ जाती है कि:

• सुविधाओं के लिए मिलने वाले सभी अनुरोधों की बुनियादी समीक्षा की जाएगी.
• डिज़ाइन पर सही लोग अपनी राय देंगे, ताकि हम ऐसे बदलावों को लागू करने में समय और संसाधन न लगाएं जो काम न करें.

शुरुआत करने के लिए, Bazel के प्रस्तावों के डेटाबेस में मौजूद डिज़ाइन से जुड़े दस्तावेज़ देखें. डिज़ाइन, काम की प्रोसेस में होते हैं. इसलिए, लागू करने से जुड़ी जानकारी में समय के साथ और सुझाव/राय के आधार पर बदलाव हो सकते हैं. पब्लिश किए गए डिज़ाइन से जुड़े दस्तावेज़ों में, शुरुआती डिज़ाइन की जानकारी होती है. इनमें, डिज़ाइन लागू करते समय किए जा रहे बदलावों की जानकारी नहीं होती. Bazel की मौजूदा सुविधाओं के बारे में जानने के लिए, हमेशा दस्तावेज़ देखें.

योगदानकर्ता का वर्कफ़्लो

योगदानकर्ता के तौर पर, डिज़ाइन से जुड़ा दस्तावेज़ लिखा जा सकता है, पुल अनुरोध भेजे जा सकते हैं, और अपने प्रस्ताव की समीक्षा करने का अनुरोध किया जा सकता है.

डिज़ाइन से जुड़ा दस्तावेज़ लिखना

डिज़ाइन से जुड़े सभी दस्तावेज़ों में हेडर होना चाहिए. इसमें ये जानकारी शामिल होनी चाहिए:

• लेखक
• अहम बदलाव की तारीख
• समीक्षकों की सूची. इसमें एक (और सिर्फ़ एक) मुख्य समीक्षक शामिल होना चाहिए
• मौजूदा स्थिति (ड्राफ़्ट, समीक्षा में है, मंज़ूर किया गया, अस्वीकार किया गया, लागू किया जा रहा है, लागू किया गया)
• चर्चा के थ्रेड का लिंक (सूचना के बाद जोड़ा जाएगा)

दस्तावेज़ को, दुनिया भर में पढ़ा जा सकने वाले Google Docs के तौर पर लिखा जा सकता है या Markdown का इस्तेमाल करके लिखा जा सकता है. Markdown और Google Docs की तुलना के बारे में नीचे पढ़ें .

ऐसे प्रस्तावों के लिए, दस्तावेज़ का एक सेक्शन होना चाहिए जिनसे उपयोगकर्ता को दिखने वाले कॉन्टेंट पर असर पड़ता है. इस सेक्शन में, पुराने सिस्टम के साथ काम करने की सुविधा पर पड़ने वाले असर की जानकारी होनी चाहिए. साथ ही, ज़रूरत पड़ने पर रोलआउट प्लान भी शामिल होना चाहिए.

पुल अनुरोध बनाना

डिज़ाइन इंडेक्स में दस्तावेज़ जोड़ने के लिए, पुल अनुरोध (पीआर) बनाकर डिज़ाइन से जुड़ा दस्तावेज़ शेयर करें . अपने पीआर में, Markdown फ़ाइल या दस्तावेज़ का लिंक जोड़ें.

अगर मुमकिन हो, तो मुख्य समीक्षक चुनें. साथ ही, अन्य समीक्षकों को सीसी करें. अगर आपने मुख्य समीक्षक नहीं चुना है, तो Bazel का रखरखाव करने वाला कोई व्यक्ति आपके पीआर को मुख्य समीक्षक असाइन करेगा.

पीआर बनाने के बाद, समीक्षक कोड की समीक्षा के दौरान शुरुआती टिप्पणियां कर सकते हैं. उदाहरण के लिए, मुख्य समीक्षक अतिरिक्त समीक्षकों के नाम सुझा सकता है या ज़रूरी जानकारी न होने की ओर इशारा कर सकता है. मुख्य समीक्षक, पीआर को तब मंज़ूरी देता है, जब उसे लगता है कि समीक्षा की प्रोसेस शुरू की जा सकती है. इसका मतलब यह नहीं है कि प्रस्ताव पूरी तरह सही है या उसे मंज़ूरी मिल जाएगी. इसका मतलब है कि प्रस्ताव में चर्चा शुरू करने के लिए ज़रूरी जानकारी मौजूद है.

नए प्रस्ताव की सूचना देना

पीआर सबमिट करने के बाद, bazel-dev को सूचना भेजें.

अन्य ग्रुप को कॉपी किया जा सकता है. उदाहरण के लिए, bazel-discuss, Bazel के एंड-यूज़र से सुझाव/राय पाने के लिए, कॉपी किया जा सकता है.

समीक्षकों के साथ मिलकर काम करना

कोई भी व्यक्ति आपके प्रस्ताव पर टिप्पणी कर सकता है. प्रश्नों के जवाब देने, प्रस्ताव के बारे में जानकारी देने, और समस्याओं को हल करने की कोशिश करें.

चर्चा, सूचना के थ्रेड पर होनी चाहिए. अगर प्रस्ताव Google Docs में है, तो टिप्पणियों का इस्तेमाल किया जा सकता है. ध्यान दें कि गुमनाम टिप्पणियां की जा सकती हैं.

स्थिति अपडेट करना

मिलकर काम करने की प्रोसेस पूरी होने के बाद, प्रस्ताव की स्थिति अपडेट करने के लिए नया पीआर बनाएं. पीआर को उसी मुख्य समीक्षक को भेजें और अन्य समीक्षकों को सीसी करें.

प्रस्ताव को आधिकारिक तौर पर स्वीकार करने के लिए, मुख्य समीक्षक पीआर को मंज़ूरी देता है. हालांकि, इससे पहले वह यह पक्का करता है कि अन्य समीक्षक भी इस फ़ैसले से सहमत हैं.

किसी प्रस्ताव की पहली सूचना और उसे मंज़ूरी मिलने के बीच कम से कम एक हफ़्ते का समय होना चाहिए. इससे यह पक्का होता है कि उपयोगकर्ताओं के पास दस्तावेज़ पढ़ने और अपनी समस्याएं शेयर करने के लिए काफ़ी समय था.

प्रस्ताव को स्वीकार किए जाने से पहले, उसे लागू किया जा सकता है. उदाहरण के लिए, कॉन्सेप्ट के सबूत या एक्सपेरिमेंट के तौर पर. हालांकि, समीक्षा पूरी होने से पहले, बदलाव सबमिट नहीं किया जा सकता.

मुख्य समीक्षक चुनना

मुख्य समीक्षक, डोमेन का ऐसा विशेषज्ञ होना चाहिए जो:

• काम के सबसिस्टम के बारे में जानकारी रखता हो
• निष्पक्ष हो और क्रिएटिव सुझाव/राय दे सकता हो
• समीक्षा की पूरी अवधि के दौरान, प्रोसेस को लीड करने के लिए उपलब्ध हो

अलग-अलग टीम लेबल के लिए संपर्क जानकारी देखें.

Markdown बनाम Google Docs

तय करें कि आपके लिए कौनसी सुविधा बेहतर है, क्योंकि दोनों को स्वीकार किया जाता है.

Google Docs का इस्तेमाल करने के फ़ायदे:

• यह ब्रेनस्टॉर्मिंग के लिए कारगर है, क्योंकि इसे आसानी से इस्तेमाल किया जा सकता है.
• साथ मिलकर बदलाव करने की सुविधा.
• तेज़ी से बदलाव करने की सुविधा.
• बदलावों के सुझाव देने का आसान तरीका.

Markdown फ़ाइलों का इस्तेमाल करने के फ़ायदे:

• लिंक करने के लिए साफ़ यूआरएल.
• संशोधनों का साफ़ रिकॉर्ड.
• लिंक को सार्वजनिक करने से पहले, ऐक्सेस के अधिकार सेट करने की ज़रूरत नहीं होती.
• सर्च इंजन की मदद से आसानी से खोजा जा सकता है.
• यह भविष्य के लिए सुरक्षित है: सादे टेक्स्ट को किसी खास टूल की ज़रूरत नहीं होती. साथ ही, इसके लिए इंटरनेट कनेक्शन की ज़रूरत नहीं होती.
• अगर लेखक अब मौजूद नहीं है, तब भी इन्हें अपडेट किया जा सकता है.
• इन्हें अपने-आप प्रोसेस किया जा सकता है. जैसे, अपडेट करना/टूटे हुए लिंक का पता लगाना, लेखकों की सूची पाना वगैरह.

पहले Google Docs पर मिलकर काम किया जा सकता है. इसके बाद, इसे Markdown में बदला जा सकता है, ताकि यह हमेशा उपलब्ध रहे.

Google Docs का इस्तेमाल करना

एक जैसा फ़ॉर्मैट इस्तेमाल करने के लिए, Bazel के डिज़ाइन से जुड़े दस्तावेज़ का टेंप्लेट इस्तेमाल करें. इसमें ज़रूरी हेडर शामिल होता है. साथ ही, यह Bazel से जुड़े अन्य दस्तावेज़ों के साथ विज़ुअल कंसिस्टेंसी बनाता है. इसके लिए, फ़ाइल > कॉपी बनाएं पर क्लिक करें या डिज़ाइन से जुड़े दस्तावेज़ के टेंप्लेट की कॉपी बनाने के लिए, इस लिंक पर क्लिक करें.

अपने दस्तावेज़ को दुनिया भर में पढ़ने लायक बनाने के लिए, शेयर करें > बेहतर सेटिंग > बदलें… पर क्लिक करें. इसके बाद, "चालू - लिंक वाले किसी भी व्यक्ति के लिए" को चुनें. अगर दस्तावेज़ पर टिप्पणियां करने की अनुमति दी जाती है, तो कोई भी व्यक्ति Google खाते के बिना भी गुमनाम तौर पर टिप्पणी कर सकता है.

Markdown का इस्तेमाल करना

दस्तावेज़, GitHub पर सेव किए जाते हैं. साथ ही, इनमें Markdown के GitHub वर्शन (खास जानकारी) का इस्तेमाल किया जाता है.

किसी मौजूदा दस्तावेज़ को अपडेट करने के लिए, पीआर बनाएं. अहम बदलावों की समीक्षा, दस्तावेज़ की समीक्षा करने वाले लोगों को करनी चाहिए. छोटे-मोटे बदलावों (जैसे, टाइप की गड़बड़ियां, फ़ॉर्मैटिंग) को कोई भी व्यक्ति मंज़ूरी दे सकता है.

समीक्षक का वर्कफ़्लो

समीक्षक, डिज़ाइन से जुड़े दस्तावेज़ों पर टिप्पणी करता है, उनकी समीक्षा करता है, और उन्हें मंज़ूरी देता है.

समीक्षक की सामान्य ज़िम्मेदारियां

डिज़ाइन से जुड़े दस्तावेज़ों की समीक्षा करना, ज़रूरत पड़ने पर ज़्यादा जानकारी मांगना, और समीक्षा की प्रोसेस पास करने वाले डिज़ाइन को मंज़ूरी देना आपकी ज़िम्मेदारी है.

नया प्रस्ताव मिलने पर

1. दस्तावेज़ पर एक नज़र डालें.
2. अगर ज़रूरी जानकारी मौजूद नहीं है या डिज़ाइन, प्रोजेक्ट के लक्ष्यों के मुताबिक नहीं है, तो टिप्पणी करें.
3. अतिरिक्त समीक्षकों के नाम सुझाएं.
4. समीक्षा के लिए तैयार होने पर, पीआर को मंज़ूरी दें.

समीक्षा की प्रोसेस के दौरान

1. ऐसी समस्याओं के बारे में डिज़ाइन के लेखक से बातचीत करें जो समस्या पैदा कर सकती हैं या जिनके बारे में ज़्यादा जानकारी की ज़रूरत है.
2. अगर सही हो, तो उन लोगों से टिप्पणियां करने के लिए कहें जो समीक्षक नहीं हैं, लेकिन उन्हें डिज़ाइन के बारे में पता होना चाहिए.
3. तय करें कि मंज़ूरी पाने के लिए, लेखक को किन टिप्पणियों पर कार्रवाई करनी होगी.
4. जब आपको प्रस्ताव की मौजूदा स्थिति पसंद आए, तो चर्चा के थ्रेड में "एलजीटीएम" (लुक्स गुड टू मी) लिखें.

डिज़ाइन की समीक्षा के सभी अनुरोधों के लिए, इस प्रोसेस को फ़ॉलो करें. Bazel पर असर डालने वाले ऐसे डिज़ाइन को मंज़ूरी न दें जो डिज़ाइन इंडेक्समें शामिल नहीं हैं .

मुख्य समीक्षक की ज़िम्मेदारियां

लंबित डिज़ाइन को लागू करने के बारे में, मंज़ूरी देने या न देने का फ़ैसला लेना आपकी ज़िम्मेदारी है. अगर ऐसा नहीं किया जा सकता, तो आपको कोई सही व्यक्ति चुनना चाहिए (पीआर को उस व्यक्ति को फिर से असाइन करें) या समस्या को हल करने के लिए, बग को Bazel के किसी मैनेजर को फिर से असाइन करना चाहिए.

समीक्षा की प्रोसेस के दौरान

1. पक्का करें कि टिप्पणी और डिज़ाइन में बदलाव करने की प्रोसेस, क्रिएटिव तरीके से आगे बढ़े.
2. मंज़ूरी देने से पहले, पक्का करें कि अन्य समीक्षकों की समस्याएं हल हो गई हों.

सभी समीक्षकों की मंज़ूरी मिलने के बाद

1. पक्का करें कि मेलिंग सूची पर सूचना दिए जाने के बाद, कम से कम एक हफ़्ता बीत चुका हो.
2. पक्का करें कि पीआर में स्थिति अपडेट की गई हो.
3. प्रस्ताव के लेखक की ओर से भेजे गए पीआर को मंज़ूरी दें.

डिज़ाइन अस्वीकार करना

1. पक्का करें कि पीआर का लेखक, पीआर भेजे. इसके अलावा, उसे पीआर भेजें.
2. पीआर में, दस्तावेज़ की स्थिति अपडेट की जाती है.
3. दस्तावेज़ में एक टिप्पणी जोड़ें. इसमें बताएं कि मौजूदा स्थिति में डिज़ाइन को मंज़ूरी क्यों नहीं दी जा सकती. साथ ही, अगले चरणों के बारे में बताएं. जैसे, "गलत मान्यताओं की समीक्षा करें और फिर से सबमिट करें".