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

7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

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

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

4. लेबल अपडेट करना

5. उस फ़्लैग को पलट दें जो काम नहीं करता.

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

उन प्रोजेक्ट के माइग्रेशन की स्थिति पर नज़र रखने के लिए, bazelisk-plus-incompatible-flags पाइपलाइन का इस्तेमाल किया जा सकता है. यहां देखें कि यह पाइपलाइन कैसे काम करती है.

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

1. Github पर समस्याएं दर्ज करें, ताकि उन डाउनस्ट्रीम प्रोजेक्ट के मालिकों को सूचना दी जा सके जो आपके बदलाव की वजह से काम नहीं कर रहे हैं.
2. डाउनस्ट्रीम प्रोजेक्ट ठीक करने के लिए, पीआर से जुड़ी अनुमतियां भेजें.
3. माइग्रेशन से जुड़ी मदद पाने के लिए, Bagel कम्यूनिटी से संपर्क करें. उदाहरण के लिए, BaZ 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 की समस्या बंद हो जाए.