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

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

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

2. GitHub से जुड़ी समस्या की शिकायत करें.

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

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

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

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

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

Bazel रिपॉज़िटरी में, GitHub पर समस्या दर्ज करें. उदाहरण देखें.

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

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

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

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

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

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

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