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

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

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

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

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

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

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

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

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

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

Basel का डेटा स्टोर करने की जगह में GitHub से जुड़ी समस्या की शिकायत करें. उदाहरण देखें.

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

• शीर्षक फ़्लैग के नाम से शुरू होता है (फ़्लैग का नाम incompatible_ से शुरू होगा).

• incompatible-change लेबल जोड़ें.

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

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

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

माइग्रेशन टूल के लिए, Buildier में योगदान दें. यह 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" लेबल जोड़ें.

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

Babel CI, ज़रूरी प्रोजेक्ट की सूची की जांच करने के लिए, BaZZ@HEAD + डाउनस्ट्रीम पर जाता है. इनमें से ज़्यादातर प्रोजेक्ट, अक्सर दूसरे बेज़ल प्रोजेक्ट पर निर्भर होते हैं. इसलिए, बड़ी कम्यूनिटी के लिए माइग्रेशन की प्रोसेस को अनब्लॉक करने के लिए, उन्हें माइग्रेट करना ज़रूरी है. इन प्रोजेक्ट के माइग्रेशन स्टेटस पर नज़र रखने के लिए, bazelisk-plus-incompatible-flags पाइपलाइन का इस्तेमाल किया जा सकता है. यहां देखें कि यह पाइपलाइन कैसे काम करती है.

हमारी डेवलपर सहायता टीम migration-ready लेबल पर नज़र रखती है. इस लेबल को GitHub की समस्या में जोड़ने के बाद, ये इन चीज़ों को हैंडल करेंगे:

1. GitHub की समस्या में एक टिप्पणी करके, माइग्रेट किए जाने वाले फ़ेलियर और डाउनस्ट्रीम प्रोजेक्ट की सूची ट्रैक करें (उदाहरण देखें)

2. GitHub से जुड़ी समस्याओं को फ़ाइल करें, ताकि जिन डाउनस्ट्रीम प्रोजेक्ट में बदलाव नहीं हुआ है उनके मालिकों को इसकी जानकारी दी जा सके. (उदाहरण देखें)

3. फ़ॉलो अप करें, ताकि यह पक्का किया जा सके कि सभी समस्याओं को, टारगेट रिलीज़ की तारीख से पहले हल कर लिया गया है

डाउनस्ट्रीम पाइपलाइन में मौजूद प्रोजेक्ट माइग्रेट करने की पूरी ज़िम्मेदारी, असंगत न होने वाले बदलाव लेखक की नहीं है, लेकिन माइग्रेशन की प्रक्रिया में तेज़ी लाने और Basel के उपयोगकर्ताओं और Basel Green Team, दोनों के जीवन को आसान बनाने के लिए आप नीचे दिए गए काम कर सकते हैं.

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

2. माइग्रेशन से जुड़ी मदद पाने के लिए, Bagel कम्यूनिटी से संपर्क करें. उदाहरण के लिए, Bagel Rules Authors SIG.

फ़्लैग फ़्लिप करना

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

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

  bazelisk-plus-incompatible-flags पाइपलाइन पर, फ़्लैग The following flags didn't break any passing Bazel team owned/co-owned projects के नीचे दिखना चाहिए.

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

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

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