ব্রেকিং পরিবর্তন রোল আউট জন্য গাইড

এটা অনিবার্য যে আমরা Bazel এ ব্রেকিং পরিবর্তন করব। আমাদের ডিজাইন পরিবর্তন করতে হবে এবং যে জিনিসগুলো পুরোপুরি কাজ করে না সেগুলো ঠিক করতে হবে। যাইহোক, আমাদের নিশ্চিত করতে হবে যে সম্প্রদায় এবং বেজেল ইকোসিস্টেম অনুসরণ করতে পারে। সেই লক্ষ্যে, Bazel প্রকল্প একটি পশ্চাদপদ সামঞ্জস্য নীতি গ্রহণ করেছে। এই দস্তাবেজটি Bazel অবদানকারীদের এই নীতি মেনে চলার জন্য Bazel-এ একটি ব্রেকিং পরিবর্তন করার প্রক্রিয়া বর্ণনা করে৷

  1. নকশা নথি নীতি অনুসরণ করুন.

  2. একটি GitHub সমস্যা ফাইল করুন।

  3. পরিবর্তনটি বাস্তবায়ন করুন।

  4. লেবেল আপডেট করুন

  5. বেমানান পতাকা উল্টান.

GitHub সমস্যা

Bazel সংগ্রহস্থলে একটি GitHub সমস্যা ফাইল করুন। উদাহরণ দেখুন।

আমরা সুপারিশ করি যে:

  • শিরোনামটি পতাকার নাম দিয়ে শুরু হয় (পতাকার নামটি incompatible_ দিয়ে শুরু হবে)।

  • আপনি incompatible-change লেবেল যোগ করুন।

  • বিবরণটিতে পরিবর্তনের একটি বিবরণ এবং প্রাসঙ্গিক নকশা নথির একটি লিঙ্ক রয়েছে৷

  • বর্ণনাটিতে একটি মাইগ্রেশন রেসিপি রয়েছে, ব্যবহারকারীদের কীভাবে তাদের কোড আপডেট করা উচিত তা ব্যাখ্যা করার জন্য। আদর্শভাবে, যখন পরিবর্তনটি যান্ত্রিক হয়, তখন একটি মাইগ্রেশন টুলের একটি লিঙ্ক অন্তর্ভুক্ত করুন।

  • বর্ণনাটিতে ব্যবহারকারীরা মাইগ্রেট না করলে যে ত্রুটি বার্তা পাবেন তার একটি উদাহরণ রয়েছে৷ এটি সার্চ ইঞ্জিন থেকে GitHub সমস্যাটিকে আরও আবিষ্কারযোগ্য করে তুলবে। নিশ্চিত করুন যে ত্রুটি বার্তাটি সহায়ক এবং কর্মযোগ্য। যখন সম্ভব, ত্রুটি বার্তাটি বেমানান পতাকার নাম অন্তর্ভুক্ত করা উচিত।

মাইগ্রেশন টুলের জন্য, Buildifier-এ অবদান রাখার কথা বিবেচনা করুন। এটি BUILD , WORKSPACE , এবং .bzl ফাইলগুলিতে স্বয়ংক্রিয় সংশোধনগুলি প্রয়োগ করতে সক্ষম৷ এটি সতর্কবার্তাও রিপোর্ট করতে পারে।

বাস্তবায়ন

Bazel একটি নতুন পতাকা তৈরি করুন. ডিফল্ট মান অবশ্যই মিথ্যা হতে হবে। সাহায্য পাঠ্যটিতে গিটহাব সমস্যার URL থাকা উচিত। যেহেতু পতাকার নামটি incompatible_ দিয়ে শুরু হয়, এটির মেটাডেটা ট্যাগ প্রয়োজন:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

কমিট বিবরণে, পতাকার একটি সংক্ষিপ্ত সারাংশ যোগ করুন। এছাড়াও RELNOTES: নিম্নলিখিত ফর্মে: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

কমিটের প্রাসঙ্গিক ডকুমেন্টেশনও আপডেট করা উচিত, যাতে কমিটের কোনো উইন্ডো না থাকে যেখানে কোডটি ডক্সের সাথে অসঙ্গতিপূর্ণ। যেহেতু আমাদের ডকুমেন্টেশন সংস্করণ করা হয়েছে, তাই ডক্সে পরিবর্তনগুলি অসাবধানতাবশত অকালে প্রকাশ করা হবে না।

লেবেল

একবার কমিট মার্জ হয়ে গেলে এবং বেমানান পরিবর্তন গৃহীত হওয়ার জন্য প্রস্তুত হলে, GitHub সমস্যাটিতে লেবেল migration-ready যোগ করুন।

যদি পতাকার সাথে একটি সমস্যা পাওয়া যায় এবং ব্যবহারকারীদের এখনও স্থানান্তরিত হওয়ার আশা না করা হয়: ফ্ল্যাগগুলি সরান migration-ready

আপনি যদি পরবর্তী বড় রিলিজে পতাকাটি উল্টানোর পরিকল্পনা করেন, তাহলে সমস্যাটিতে লেবেল `ব্রেকিং-চেঞ্জ-এক্স.০' যোগ করুন।

সংগ্রহস্থল আপডেট করা হচ্ছে

Bazel CI Bazel@HEAD + Downstream এ গুরুত্বপূর্ণ প্রকল্পের একটি তালিকা পরীক্ষা করে। তাদের বেশিরভাগই প্রায়শই অন্যান্য Bazel প্রকল্পের নির্ভরতা, তাই বৃহত্তর সম্প্রদায়ের জন্য মাইগ্রেশন আনব্লক করতে তাদের স্থানান্তর করা গুরুত্বপূর্ণ।

এই প্রকল্পগুলির স্থানান্তর স্থিতি নিরীক্ষণ করতে, আপনি bazelisk-plus-incompatible-flags পাইপলাইন ব্যবহার করতে পারেন, এই পাইপলাইনটি এখানে কীভাবে কাজ করে তা পরীক্ষা করুন৷

ডাউনস্ট্রিম পাইপলাইনে প্রকল্প স্থানান্তর করা সম্পূর্ণরূপে বেমানান পরিবর্তন লেখকের দায়িত্ব নয়। কিন্তু আপনি মাইগ্রেশনকে ত্বরান্বিত করতে এবং Bazel ব্যবহারকারী এবং Bazel Green Team উভয়ের জন্য জীবনকে সহজ করতে নিম্নলিখিতগুলি করতে পারেন৷

  1. আপনার অসামঞ্জস্যপূর্ণ পরিবর্তন দ্বারা ভাঙ্গা ডাউনস্ট্রিম প্রকল্পগুলির মালিকদের অবহিত করার জন্য Github সমস্যাগুলি ফাইল করুন৷
  2. ডাউনস্ট্রিম প্রকল্পগুলি ঠিক করতে PR পাঠান।
  3. মাইগ্রেশনে সাহায্যের জন্য 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 ফাইলে পতাকার মান মিথ্যাতে সেট করার কথা বিবেচনা করুন৷ এটি করার মাধ্যমে, আমরা নিশ্চিত করতে পারি যে 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 সমস্যাটি বন্ধ হয়ে যায়।