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

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