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

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

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

2. GitHub पर समस्या की शिकायत करें.

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

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

5. ऐसे फ़्लैग को चालू करें जो पुराने वर्शन के साथ काम नहीं करता.

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 + डाउनस्ट्रीम पर, अहम प्रोजेक्ट की सूची की जांच करता है. इनमें से ज़्यादातर प्रोजेक्ट, अक्सर Bazel के अन्य प्रोजेक्ट की डिपेंडेंसी होते हैं. इसलिए, इन्हें माइग्रेट करना ज़रूरी है, ताकि बड़ी कम्यूनिटी के लिए माइग्रेशन को रोका न जाए.

इन प्रोजेक्ट के माइग्रेशन की स्थिति की निगरानी करने के लिए, आप bazelisk-plus-incompatible-flags पाइपलाइन का इस्तेमाल कर सकते हैं. इस पाइपलाइन के काम करने का तरीका यहां देखें.

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

1. GitHub पर समस्या की शिकायत करें, ताकि पुराने वर्शन के साथ काम न करने वाले आपके बदलाव की वजह से, डाउनस्ट्रीम प्रोजेक्ट के मालिकों को सूचना दी जा सके.
2. डाउनस्ट्रीम प्रोजेक्ट को ठीक करने के लिए, पीआर भेजें.
3. माइग्रेशन में मदद पाने के लिए, Bazel कम्यूनिटी से संपर्क करें. जैसे, Bazel Rules Authors SIG.

फ़्लैग को चालू करना

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

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

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

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

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

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

• कमिट के ब्यौरे में, 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 पर समस्या की शिकायत करने वाला पेज बंद हो जाए.