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

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