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

समस्या की शिकायत करें सोर्स देखें

इसलिए, हम 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 Green Team और Bazel Green Team, दोनों के काम को आसान बनाने के लिए नीचे दिया गया तरीका अपना सकते हैं.

1. डाउनस्ट्रीम प्रोजेक्ट ठीक करने के लिए पीआर भेजें.

2. माइग्रेशन में मदद पाने के लिए, Bazel कम्यूनिटी से संपर्क करें. उदाहरण के लिए, Bazel नियम लेखक एसआईजी.

झंडे को उछालना

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

• नेटवर्क में मौजूद मुख्य डेटा स्टोर करने की जगहों को माइग्रेट किया जाता है.

  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 से जुड़ी समस्या बंद हो जाए.