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