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

हम 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" लेबल जोड़ें.

डेटा स्टोर करने की जगहें अपडेट की जा रही हैं

Basel CI, Baडेल@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 में दिखना चाहिए.

• चेकलिस्ट में मौजूद सभी समस्याओं को 'ठीक की गई'/'बंद है' के तौर पर मार्क किया जाता है.

• उपयोगकर्ता की समस्याओं और सवालों को हल कर दिया गया है.

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