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

किसी समस्या की शिकायत करें सोर्स देखें रात · 7.4 को अपनाएं. 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

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

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

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

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

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

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

GitHub से जुड़ी समस्या दर्ज करना बेज़ल रिपॉज़िटरी में. उदाहरण देखें.

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

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

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

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

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

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

माइग्रेशन टूल के लिए, इसमें योगदान दें बिल्डिफ़ायर. यह BUILD, WORKSPACE, और .bzl फ़ाइलों में अपने-आप गड़बड़ियां ठीक कर सकती है. यह चेतावनियों की भी रिपोर्ट कर सकता है.

लागू करना

Bazel में नया फ़्लैग बनाएं. डिफ़ॉल्ट मान गलत होना चाहिए. सहायता टेक्स्ट इसमें GitHub की समस्या का यूआरएल शामिल होना चाहिए. झंडे का नाम इससे शुरू होता है incompatible_, इसे मेटाडेटा टैग की ज़रूरत है:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

कमिट के ब्यौरे में, फ़्लैग के बारे में कम शब्दों में जानकारी जोड़ें. नीचे दिए गए फ़ॉर्म में RELNOTES: भी जोड़ें: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

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

लेबल

तय की गई कीमत को मर्ज करने और काम न करने वाले बदलाव को लागू करने के लिए तैयार होने के बाद, लेबल जोड़ें migration-ready समस्या को हल करने में मदद मिलेगी.

अगर फ़्लैग में कोई समस्या मिलती है और उपयोगकर्ताओं को अभी माइग्रेट करने की उम्मीद नहीं है, तो: migration-ready फ़्लैग हटाएं.

अगर आपको अगली बड़ी रिलीज़ में फ़्लैग को फ़्लिप करना है, तो समस्या में `breaking-change-X.0" लेबल जोड़ें.

रिपॉज़िटरी अपडेट करना

Bazel CI, Bazel@HEAD + Downstream पर मौजूद अहम प्रोजेक्ट की सूची की जांच करता है. इनमें से ज़्यादातर लोग अक्सर इसलिए, ज़रूरी है कि अन्य Ba बैंक के प्रोजेक्ट की डिपेंडेंसी हो, ताकि पूरी कम्यूनिटी के लिए माइग्रेशन की प्रोसेस को अनब्लॉक किया जा सके. इन प्रोजेक्ट के माइग्रेशन स्टेटस पर नज़र रखने के लिए, 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 पर फ़्लिप करने के बाद, इसे बाद में Basel से हटा दिया जाना चाहिए. अगर आपको ऐसे फ़्लैग को हटाना है जो काम नहीं करता, तो:

  • अगर यह कोई ऐसा बदलाव है जो आपके ऐप्लिकेशन के साथ काम नहीं करता, तो उपयोगकर्ताओं को माइग्रेट करने के लिए ज़्यादा समय दें. आम तौर पर, फ़्लैग कम से कम एक मुख्य रिलीज़ में उपलब्ध होना चाहिए.
  • फ़्लैग हटाने वाले कमिट के लिए, ब्यौरे में Fixes #abc का इस्तेमाल करें, ताकि कमिट मर्ज होने पर GitHub की समस्या बंद हो जाए.