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

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

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

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

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

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

5. डेटाबेस अपडेट करें.

6. पुराने वर्शन के साथ काम न करने वाले फ़्लैग को चालू करें.

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 पाइपलाइन का इस्तेमाल किया जा सकता है. यहां देखें कि यह पाइपलाइन कैसे काम करती है यहां.

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

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

2. GitHub पर समस्या की शिकायत करें, ताकि पुराने वर्शन के साथ काम न करने वाले आपके बदलाव की वजह से, डाउनस्ट्रीम के हर प्रोजेक्ट के मालिकों को सूचना दी जा सके (उदाहरण देखें)

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

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

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

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