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

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

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

2. GitHub पर समस्या दर्ज करें.

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

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

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

6. काम न करने वाले फ़्लैग को हटाएं.

GitHub से जुड़ी समस्या

Basel का डेटा स्टोर करने की जगह में GitHub से जुड़ी समस्या की शिकायत करें. उदाहरण देखें.

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

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

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

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

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

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

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

लागू करना

बेज़ेल में नया फ़्लैग बनाएं. डिफ़ॉल्ट वैल्यू 'गलत' होनी चाहिए. सहायता टेक्स्ट में 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 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 फ़ाइल में फ़्लैग की वैल्यू को 'गलत' पर सेट करें. ऐसा करके, हम यह पक्का कर सकते हैं कि Basel के उपयोगकर्ता, जल्द से जल्द डिफ़ॉल्ट रूप से नए व्यवहार पर निर्भर रहें.

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

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