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

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

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

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

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

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

5. ऐसी टारगेटिंग के लिए फ़्लैग हटाएं जो Gmail विज्ञापन में काम नहीं करती.

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

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

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

1. Github पर फ़ाइल से जुड़ी समस्याएं सबमिट करें, ताकि उन डाउनस्ट्रीम प्रोजेक्ट के मालिकों को सूचना दी जा सके जो आपके बदलाव की वजह से काम नहीं कर रहे हैं.
2. डाउनस्ट्रीम प्रोजेक्ट में मौजूद समस्याओं को ठीक करने के लिए, पीआर भेजें.
3. माइग्रेट करने से जुड़ी मदद पाने के लिए, Bazel कम्यूनिटी से संपर्क करें. उदाहरण के लिए, Bazel Rules Authors SIG.

फ़्लैग को पहले जैसा करना

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

• इकोसिस्टम में मौजूद मुख्य रिपॉज़िटरी माइग्रेट कर दी गई हैं.

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

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

अगर Bazel में फ़्लैग चालू करने की सुविधा उपलब्ध है, लेकिन Google में इंटरनल माइग्रेशन की वजह से यह सुविधा चालू नहीं की जा सकती, तो कृपया इंटरनल blazerc फ़ाइल में फ़्लैग की वैल्यू को false पर सेट करें, ताकि फ़्लैग चालू करने की सुविधा को अनब्लॉक किया जा सके. ऐसा करने से, हम यह पक्का कर सकते हैं कि 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 की समस्या बंद हो जाए.