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

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