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

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

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

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

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

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

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

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

  6. काम न करने वाले फ़्लैग को फ़्लिप करें.

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

Bazel डेटा स्टोर करने की जगह में GitHub की एक समस्या दर्ज करें. उदाहरण देखें.

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

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

  • आप लेबल incompatible-change जोड़ते हैं.

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

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

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

माइग्रेशन टूल के लिए, Builder में योगदान दें. यह 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 पाइपलाइन का इस्तेमाल किया जा सकता है. यह पाइपलाइन कैसे काम करती है, यहां देखें.

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

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

  2. GitGitHub से जुड़ी समस्याएं दर्ज करें, ताकि हर डाउनस्ट्रीम प्रोजेक्ट के मालिकों को ऐसे बदलाव की जानकारी दी जा सके जो आपके काम न करने वाले बदलाव के हिसाब से अलग-अलग हों. (उदाहरण देखें)

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

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

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

  2. माइग्रेशन में मदद पाने के लिए, Bazel कम्यूनिटी से संपर्क करें (उदाहरण के लिए, Bazel Rules के लेखक 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 समस्या बंद हो जाए.