नुकसान पहुंचा सकने वाले बदलावों को रोल आउट करने के लिए गाइड

हम Bazel में ऐसे बदलाव करेंगे जिनसे उपयोगकर्ताओं को परेशानी हो सकती है. हमें अपने डिज़ाइन में बदलाव करना होगा और उन चीज़ों को ठीक करना होगा जो ठीक से काम नहीं कर रही हैं. हालांकि, हमें यह पक्का करना होगा कि कम्यूनिटी और Bazel नेटवर्क इसका पालन कर सकें. इसके लिए, Bazel प्रोजेक्ट ने पुराने सिस्टम के साथ काम करने की नीति अपनाई है. इस दस्तावेज़ में, Bazel में योगदान देने वाले लोगों के लिए, इस नीति का पालन करने के लिए Bazel में बड़ा बदलाव करने की प्रोसेस के बारे में बताया गया है.

1. डिज़ाइन दस्तावेज़ की नीति का पालन करें.

2. GitHub से जुड़ी समस्या की शिकायत करें.

3. बदलाव लागू करें.

4. लेबल अपडेट करें.

5. रिपॉज़िटरी अपडेट करें.

6. ऐसी टारगेटिंग के लिए फ़्लैग हटाएं जो Gmail विज्ञापन में काम नहीं करती.

GitHub में समस्या

Bazel रिपॉज़िटरी में GitHub की समस्या की रिपोर्ट करें. उदाहरण देखें.

हमारा सुझाव है कि:

• टाइटल की शुरुआत फ़्लैग के नाम से होती है. फ़्लैग का नाम incompatible_ से शुरू होता है.

• आपने लेबल incompatible-change जोड़ा है.

• ब्यौरे में बदलाव की जानकारी और डिज़ाइन से जुड़े ज़रूरी दस्तावेज़ों का लिंक शामिल होता है.

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

• ब्यौरे में, गड़बड़ी के उस मैसेज का उदाहरण शामिल है जो माइग्रेट न करने पर उपयोगकर्ताओं को मिलेगा. इससे सर्च इंजन पर GitHub की समस्या को आसानी से खोजा जा सकेगा. पक्का करें कि गड़बड़ी का मैसेज मददगार हो और उसमें कार्रवाई करने के बारे में जानकारी दी गई हो. अगर हो सके, तो गड़बड़ी के मैसेज में उस फ़्लैग का नाम शामिल करें जो काम नहीं करता.

माइग्रेशन टूल के लिए, Buildifier में योगदान दें. यह BUILD, WORKSPACE, और .bzl फ़ाइलों में अपने-आप ठीक होने की सुविधा लागू कर सकता है. यह चेतावनियों की जानकारी भी दे सकता है.

लागू करना

Bazel में नया फ़्लैग बनाएं. डिफ़ॉल्ट वैल्यू, गलत होनी चाहिए. सहायता टेक्स्ट में, GitHub की समस्या का यूआरएल होना चाहिए. फ़्लैग का नाम incompatible_ से शुरू होता है. इसलिए, इसके लिए मेटाडेटा टैग ज़रूरी हैं:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

कमिट के ब्यौरे में, फ़्लैग के बारे में कम शब्दों में जानकारी दें. साथ ही, RELNOTES: को इस फ़ॉर्म में जोड़ें: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

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

लेबल

कमिट मर्ज होने और असंगत बदलाव को लागू करने के लिए तैयार होने के बाद, GitHub की समस्या में migration-ready लेबल जोड़ें.

अगर फ़्लैग में कोई समस्या मिलती है और उपयोगकर्ताओं को अभी माइग्रेट नहीं करना है, तो फ़्लैग migration-ready हटाएं.

अगर आपको अगली मुख्य रिलीज़ में फ़्लैग को फ़्लिप करना है, तो समस्या में `breaking-change-X.0" लेबल जोड़ें.

रिपॉज़िटरी अपडेट की जा रही हैं

Bazel CI, Bazel@HEAD + Downstream पर, अहम प्रोजेक्ट की सूची की जाँच करता है. इनमें से ज़्यादातर, अक्सर अन्य Bazel प्रोजेक्ट की डिपेंडेंसी होती हैं. इसलिए, इन्हें माइग्रेट करना ज़रूरी है, ताकि बड़ी कम्यूनिटी के लिए माइग्रेशन को अनब्लॉक किया जा सके. उन प्रोजेक्ट के माइग्रेशन की स्थिति पर नज़र रखने के लिए, bazelisk-plus-incompatible-flags पाइपलाइन का इस्तेमाल किया जा सकता है. जानें कि यह पाइपलाइन कैसे काम करती है. इसके लिए, यहां क्लिक करें.

डेवलपर सहायता टीम, migration-ready लेबल पर नज़र रखती है. GitHub की समस्या में यह लेबल जोड़ने के बाद, ये काम किए जाएंगे:

1. GitHub की समस्या में एक टिप्पणी बनाएं, ताकि माइग्रेट किए जाने वाले फ़ेल प्रोजेक्ट और डाउनस्ट्रीम प्रोजेक्ट की सूची को ट्रैक किया जा सके (उदाहरण देखें)

2. Github पर फ़ाइल से जुड़ी समस्याएं सबमिट करें, ताकि उन सभी डाउनस्ट्रीम प्रोजेक्ट के मालिकों को सूचना दी जा सके जिनमें आपके बदलाव की वजह से समस्याएं आई हैं (उदाहरण देखें)

3. यह पक्का करने के लिए फ़ॉलो अप करें कि रिलीज़ की तय तारीख से पहले सभी समस्याओं को हल कर लिया गया है

डाउनस्ट्रीम पाइपलाइन में प्रोजेक्ट माइग्रेट करने की पूरी ज़िम्मेदारी, ऐसे बदलाव करने वाले व्यक्ति की नहीं होती जो Bazel के साथ काम नहीं करते. हालांकि, माइग्रेशन की प्रोसेस को तेज़ करने और Bazel के उपयोगकर्ताओं और Bazel Green Team, दोनों के लिए इसे आसान बनाने के लिए, ये काम किए जा सकते हैं.

1. डाउनस्ट्रीम प्रोजेक्ट को ठीक करने के लिए, पीआर भेजें.

2. माइग्रेट करने से जुड़ी मदद पाने के लिए, Bazel कम्यूनिटी से संपर्क करें. उदाहरण के लिए, Bazel Rules Authors SIG.

फ़्लैग को पहले जैसा करना

फ़्लैग की डिफ़ॉल्ट वैल्यू को true पर सेट करने से पहले, कृपया पक्का करें कि:

• इकोसिस्टम में मौजूद मुख्य रिपॉज़िटरी माइग्रेट कर दी गई हैं.

  bazelisk-plus-incompatible-flags पाइपलाइन पर, फ़्लैग, The following flags didn't break any passing Bazel team owned/co-owned projects में दिखना चाहिए.

• चेकलिस्ट में मौजूद सभी समस्याओं को 'ठीक कर लिया गया' या 'बंद कर दिया गया' के तौर पर मार्क किया गया हो.

• उपयोगकर्ता की समस्याओं और सवालों को हल कर दिया गया है.

अगर Bazel में फ़्लैग चालू करने की सुविधा उपलब्ध है, लेकिन Google में इंटरनल माइग्रेशन की वजह से यह सुविधा चालू नहीं की जा सकती, तो कृपया इंटरनल blazerc फ़ाइल में फ़्लैग की वैल्यू को false पर सेट करें, ताकि फ़्लैग चालू करने की सुविधा को अनब्लॉक किया जा सके. ऐसा करने से, हम यह पक्का कर सकते हैं कि Bazel के उपयोगकर्ता, डिफ़ॉल्ट रूप से जल्द से जल्द नए वर्शन का इस्तेमाल करें.

फ़्लैग के डिफ़ॉल्ट मान को true पर सेट करते समय, कृपया:

• कमिट के ब्यौरे में RELNOTES[INC] का इस्तेमाल करें. इसके लिए, इस फ़ॉर्मैट का इस्तेमाल करें: RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details कमिट के ब्यौरे में अन्य जानकारी भी शामिल की जा सकती है.
• ब्यौरे में Fixes #xyz का इस्तेमाल करें, ताकि कमिट मर्ज होने पर GitHub की समस्या बंद हो जाए.
• ज़रूरत पड़ने पर, दस्तावेज़ की समीक्षा करें और उसे अपडेट करें.
• फ़्लैग हटाने की प्रोसेस को ट्रैक करने के लिए, नई समस्या #abc दर्ज करें.

फ़्लैग हटाना

HEAD पर फ़्लैग फ़्लिप होने के बाद, इसे Bazel से हटा दिया जाना चाहिए. जब आपको काम न करने वाले फ़्लैग को हटाना हो, तब:

• अगर कोई बड़ा बदलाव किया गया है जो काम नहीं करता है, तो उपयोगकर्ताओं को माइग्रेट करने के लिए ज़्यादा समय दें. आम तौर पर, फ़्लैग कम से कम एक मुख्य रिलीज़ में उपलब्ध होना चाहिए.
• फ़्लैग हटाने वाले कमिट के लिए, ब्यौरे में Fixes #abc का इस्तेमाल करें, ताकि कमिट मर्ज होने पर GitHub की समस्या बंद हो जाए.