تغییرنامه‌های (Changesets) فرانت‌اند: راهنمای جامع مدیریت نسخه

در دنیای همیشه در حال تحول توسعه فرانت‌اند، مدیریت مؤثر تغییرات و انتشارها برای حفظ پایداری پروژه و تضمین همکاری روان، حیاتی است. تغییرنامه‌های فرانت‌اند (Frontend Changesets) یک راهکار قدرتمند و انعطاف‌پذیر برای کنترل نسخه، مدیریت وابستگی‌ها و خودکارسازی فرآیند انتشار ارائه می‌دهند. این راهنما به جزئیات تغییرنامه‌های فرانت‌اند می‌پردازد و همه چیز را از راه‌اندازی اولیه تا پیکربندی پیشرفته پوشش می‌دهد و مثال‌های عملی و بینش‌های کاربردی برای کمک به شما در تسلط بر این ابزار ضروری ارائه می‌کند.

تغییرنامه‌های فرانت‌اند چه هستند؟

Frontend Changesets ابزاری است که برای مدیریت نسخه‌بندی و انتشار پکیج‌های جاوااسکریپت، به ویژه در مونوریپوها (monorepos)، طراحی شده است. این ابزار فرآیند ایجاد گزارش تغییرات (changelogs)، به‌روزرسانی نسخه‌های پکیج و انتشار در رجیستری‌های پکیج مانند npm را خودکار می‌کند. تغییرنامه‌ها اساساً فایل‌های کوچک و متمرکزی هستند که تغییرات اعمال شده بر روی یک پکیج یا کامپوننت خاص را توصیف می‌کنند. این فایل‌ها سپس برای تولید یادداشت‌های انتشار، به‌روزرسانی نسخه‌های پکیج و مدیریت وابستگی‌ها استفاده می‌شوند.

در مقایسه با رویکردهای سنتی نسخه‌بندی، Changesets چندین مزیت کلیدی ارائه می‌دهد:

• همکاری بهبودیافته: تغییرنامه‌ها فرآیند همکاری در پروژه‌های بزرگ با چندین مشارکت‌کننده را ساده می‌کنند. با تعریف واضح تأثیر هر تغییر، Changesets درک و بررسی مشارکت‌ها را برای اعضای تیم آسان‌تر می‌کند.
• انتشارهای خودکار: تغییرنامه‌ها فرآیند انتشار را خودکار می‌کنند، که خطر خطای انسانی را کاهش داده و از نسخه‌بندی یکپارچه در تمام پکیج‌ها اطمینان حاصل می‌کند.
• شفافیت افزایش‌یافته: تغییرنامه‌ها یک سابقه شفاف از تمام تغییرات اعمال شده بر پروژه ارائه می‌دهند، که ردیابی باگ‌ها و درک سیر تکاملی کدبیس را آسان‌تر می‌کند.
• پشتیبانی از مونوریپو: تغییرنامه‌ها به ویژه برای مدیریت مونوریپوها، که در آن چندین پکیج در یک ریپازیتوری واحد قرار دارند، مناسب هستند. آنها یک رویکرد متمرکز و یکپارچه برای نسخه‌بندی و انتشار پکیج‌ها در مونوریپو ارائه می‌دهند.

شروع کار با تغییرنامه‌های فرانت‌اند

برای شروع استفاده از تغییرنامه‌های فرانت‌اند، باید پکیج‌های لازم را نصب کرده و ابزار را در پروژه خود مقداردهی اولیه کنید. در اینجا یک راهنمای گام به گام ارائه شده است:

۱. نصب

پکیج اصلی `@changesets/cli` را به عنوان یک وابستگی توسعه (development dependency) نصب کنید:

            npm install @changesets/cli --save-dev
# or
yarn add @changesets/cli --dev
            

              
                Copy
              
            
          

۲. مقداردهی اولیه

Changesets را در پروژه خود با اجرای دستور زیر مقداردهی اولیه کنید:

            npx changeset init
            

              
                Copy
              
            
          

این دستور یک دایرکتوری `.changeset` در ریشه پروژه شما به همراه یک فایل پیکربندی (`.changeset/config.json`) ایجاد می‌کند.

۳. پیکربندی Changesets

فایل `config.json` به شما امکان می‌دهد رفتار Changesets را سفارشی کنید. در اینجا یک پیکربندی معمول آورده شده است:

            {
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "ignore": []
}
            

              
                Copy
              
            
          

بیایید هر گزینه را بررسی کنیم:

• `changelog`: آداپتور مورد استفاده برای تولید ورودی‌های گزارش تغییرات را مشخص می‌کند. آداپتور پیش‌فرض `@changesets/cli/changelog` از قالب‌بندی Markdown استفاده می‌کند.
• `commit`: تعیین می‌کند که آیا Changesets باید به طور خودکار تغییرات را در ریپازیتوری کامیت کند یا خیر. تنظیم این گزینه روی `false` به شما امکان می‌دهد تغییرات را به صورت دستی بررسی و کامیت کنید.
• `fixed`: آرایه‌ای از نام‌های پکیج که باید همیشه با هم و با یک نسخه یکسان منتشر شوند. این برای پکیج‌هایی که به شدت به هم مرتبط هستند مفید است.
• `linked`: آرایه‌ای از وابستگی‌ها که باید در طول توسعه به هم متصل شوند. این به شما امکان می‌دهد تغییرات را در چندین پکیج بدون انتشار آنها آزمایش کنید.
• `access`: سطح دسترسی پکیج‌های منتشر شده را تعیین می‌کند. سطح دسترسی پیش‌فرض `public` پکیج‌ها را به صورت عمومی در npm در دسترس قرار می‌دهد.
• `baseBranch`: شاخه پایه برای مقایسه هنگام تعیین اینکه کدام پکیج‌ها تغییر کرده‌اند را مشخص می‌کند. این معمولاً روی شاخه اصلی ریپازیتوری شما تنظیم می‌شود (مثلاً `main`، `master`).
• `ignore`: آرایه‌ای از فایل‌ها یا دایرکتوری‌ها که باید هنگام تعیین اینکه کدام پکیج‌ها تغییر کرده‌اند، نادیده گرفته شوند.

ایجاد یک تغییرنامه

برای ایجاد یک تغییرنامه، دستور زیر را اجرا کنید:

            npx changeset
            

              
                Copy
              
            
          

این دستور از شما می‌خواهد پکیج‌هایی را که تغییر کرده‌اند انتخاب کنید و توضیحی از تغییرات ارائه دهید. توضیحات باید واضح، مختصر و آموزنده باشند و هدف و تأثیر تغییرات را توضیح دهند. برای مثال:

            Fix: Corrected a bug in the button component that caused it to display incorrectly on mobile devices.

This changeset fixes a bug in the `Button` component that caused it to render with incorrect styling on mobile devices. The issue was caused by a CSS specificity conflict. This change resolves the conflict and ensures that the button component displays correctly across all devices.
            

              
                Copy
              
            
          

سپس Changesets یک فایل Markdown در دایرکتوری `.changeset` حاوی اطلاعاتی که شما ارائه کرده‌اید، ایجاد می‌کند. این فایل بعداً برای تولید یادداشت‌های انتشار و به‌روزرسانی نسخه‌های پکیج استفاده خواهد شد.

مدیریت وابستگی‌ها با Changesets

Changesets همچنین می‌تواند برای مدیریت وابستگی‌ها بین پکیج‌ها در یک مونوریپو استفاده شود. هنگام ایجاد یک تغییرنامه، می‌توانید مشخص کنید کدام پکیج‌ها به پکیج تغییر یافته وابسته هستند. این تضمین می‌کند که پکیج‌های وابسته نیز هنگام انتشار پکیج تغییر یافته، به‌روزرسانی شوند.

برای مثال، اگر دو پکیج `package-a` و `package-b` دارید و `package-b` به `package-a` وابسته است، می‌توانید یک تغییرنامه برای `package-a` ایجاد کنید و مشخص کنید که `package-b` به آن وابسته است. هنگامی که دستور `version` (که در ادامه توضیح داده شده) را اجرا می‌کنید، Changesets به طور خودکار نسخه `package-b` را برای انعکاس تغییرات در `package-a` به‌روزرسانی می‌کند.

نسخه‌بندی و انتشار

پس از ایجاد یک یا چند تغییرنامه، می‌توانید از دستور `version` برای به‌روزرسانی نسخه‌های پکیج و تولید گزارش تغییرات استفاده کنید.

            npx changeset version
            

              
                Copy
              
            
          

این دستور کارهای زیر را انجام می‌دهد:

• تغییرنامه‌های موجود در دایرکتوری `.changeset` را می‌خواند.
• افزایش نسخه مناسب برای هر پکیج را بر اساس تغییرنامه‌ها تعیین می‌کند.
• فایل‌های `package.json` را با نسخه‌های جدید به‌روزرسانی می‌کند.
• ورودی‌های گزارش تغییرات را برای هر پکیج تولید می‌کند.
• تغییرات را در ریپازیتوری کامیت می‌کند.

پس از اجرای دستور `version`، می‌توانید پکیج‌ها را با استفاده از دستور `publish` در npm منتشر کنید:

            npx changeset publish
            

              
                Copy
              
            
          

این دستور کارهای زیر را انجام می‌دهد:

• پکیج‌ها را می‌سازد (در صورت لزوم).
• پکیج‌ها را در npm منتشر می‌کند.
• تغییرنامه‌ها را از دایرکتوری `.changeset` حذف می‌کند.

یکپارچه‌سازی Changesets با CI/CD

Changesets برای یکپارچه‌سازی با پایپ‌لاین‌های CI/CD (یکپارچه‌سازی و تحویل مداوم) طراحی شده است. این به شما امکان می‌دهد فرآیند انتشار را خودکار کرده و اطمینان حاصل کنید که تغییرات به سرعت و با اطمینان مستقر می‌شوند.

در اینجا یک گردش کار CI/CD معمول برای Changesets آورده شده است:

1. کامیت تغییرات: توسعه‌دهندگان تغییرات را به همراه تغییرنامه‌ها در ریپازیتوری کامیت می‌کنند.
2. ساخت CI: سیستم CI تست‌ها را اجرا کرده و پروژه را می‌سازد.
3. نسخه‌بندی و انتشار: سیستم CI دستورات `version` و `publish` را از Changesets برای به‌روزرسانی نسخه‌های پکیج، تولید گزارش تغییرات و انتشار پکیج‌ها در npm اجرا می‌کند. این مرحله اغلب از یک توکن یا اعتبارنامه خودکار برای دسترسی به npm استفاده می‌کند.
4. استقرار: سیستم CI پکیج‌های به‌روز شده را در محیط تولید مستقر می‌کند.

چندین ارائه‌دهنده CI/CD پشتیبانی داخلی برای Changesets ارائه می‌دهند. برای مثال، GitHub Actions یک اکشن اختصاصی برای اجرای Changesets فراهم می‌کند:

            name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - name: Install dependencies
        run: npm install
      - name: Create Release Pull Request or publish to npm
        id: changesets
        uses: changesets/action@v1
        with:
          # This makes sure we can read the token even if it's not
          # available on the PR. This prevents an error from occurring in
          # the publish step below.
          publish: npm run release
          version: npm run version
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

            

              
                Copy
              
            
          

این گردش کار به طور خودکار دستورات `version` و `publish` را هر زمان که تغییراتی به شاخه `main` پوش می‌شود، اجرا می‌کند. همچنین یک پول ریکوئست حاوی فایل‌های `package.json` به‌روز شده و گزارش تغییرات ایجاد می‌کند.

پیکربندی پیشرفته

Changesets چندین گزینه پیکربندی پیشرفته ارائه می‌دهد که به شما امکان می‌دهد ابزار را برای برآوردن نیازهای خاص خود سفارشی کنید. برخی از مفیدترین گزینه‌ها عبارتند از:

• آداپتورهای سفارشی گزارش تغییرات: می‌توانید آداپتورهای گزارش تغییرات خود را برای تولید گزارش تغییرات در قالبی که متناسب با پروژه شما باشد، ایجاد کنید.
• استراتژی‌های نسخه‌بندی سفارشی: می‌توانید استراتژی‌های نسخه‌بندی خود را برای کنترل نحوه افزایش نسخه‌های پکیج تعریف کنید.
• پیکربندی ویژه مونوریپو: Changesets گزینه‌های پیکربندی خاصی برای مدیریت مونوریپوها ارائه می‌دهد، مانند توانایی مشخص کردن پکیج‌هایی که باید در یک انتشار گنجانده شوند.

آداپتورهای سفارشی گزارش تغییرات

آداپتور پیش‌فرض گزارش تغییرات از قالب‌بندی Markdown استفاده می‌کند که برای اکثر پروژه‌ها مناسب است. با این حال، اگر نیاز به تولید گزارش تغییرات در قالب دیگری دارید، می‌توانید آداپتور سفارشی خود را ایجاد کنید. یک آداپتور سفارشی به سادگی یک ماژول جاوااسکریپت است که تابعی را اکسپورت می‌کند که یک شیء Changeset را به عنوان ورودی می‌گیرد و یک رشته حاوی ورودی گزارش تغییرات را برمی‌گرداند. در اینجا یک مثال آورده شده است:

            // my-custom-changelog-adapter.js
module.exports = async function getReleaseLine(changeset, versionType, options) {
  if (changeset.commit) {
    return `- ${changeset.summary} (commit: ${changeset.commit})\n`;
  } else {
    return `- ${changeset.summary}\n`;
  }
};

            

              
                Copy
              
            
          

برای استفاده از آداپتور سفارشی خود، باید گزینه `changelog` را در فایل `config.json` به‌روزرسانی کنید:

            {
  "changelog": "./my-custom-changelog-adapter.js",
  ...
}
            

              
                Copy
              
            
          

استراتژی‌های نسخه‌بندی سفارشی

Changesets به طور پیش‌فرض از استراتژی نسخه‌بندی معنایی (SemVer) استفاده می‌کند، به این معنی که نسخه‌های پکیج بر اساس نوع تغییرات انجام شده (مثلاً major، minor، patch) افزایش می‌یابند. با این حال، می‌توانید استراتژی‌های نسخه‌بندی خود را برای کنترل نحوه افزایش نسخه‌های پکیج تعریف کنید. این در صورتی مفید است که الزامات نسخه‌بندی خاصی داشته باشید یا بخواهید از یک طرح نسخه‌بندی متفاوت استفاده کنید.

برای تعریف یک استراتژی نسخه‌بندی سفارشی، باید یک ماژول جاوااسکریپت ایجاد کنید که تابعی را اکسپورت می‌کند که یک شیء Changeset را به عنوان ورودی می‌گیرد و نوع افزایش نسخه (مثلاً `major`، `minor`، `patch`) را برمی‌گرداند. در اینجا یک مثال آورده شده است:

            // my-custom-versioning-strategy.js
module.exports = async function determineVersion(changeset, options) {
  if (changeset.summary.includes("breaking change")) {
    return "major";
  } else if (changeset.summary.includes("feature")) {
    return "minor";
  } else {
    return "patch";
  }
};

            

              
                Copy
              
            
          

در حال حاضر، استراتژی‌های نسخه‌بندی سفارشی نیاز به پیکربندی عمیق‌تری دارند و مستقیماً از طریق `config.json` پشتیبانی نمی‌شوند. این یک مورد استفاده پیشرفته است و معمولاً شامل سفارشی‌سازی گردش کار Changesets در سطح پایین‌تر می‌شود.

بهترین شیوه‌ها برای استفاده از تغییرنامه‌های فرانت‌اند

برای به حداکثر رساندن مزایای تغییرنامه‌های فرانت‌اند، این بهترین شیوه‌ها را دنبال کنید:

• توضیحات واضح و مختصر برای تغییرنامه بنویسید: توضیحات تغییرنامه مهم‌ترین بخش آن است. اطمینان حاصل کنید که توضیحات واضح، مختصر و آموزنده‌ای بنویسید که هدف و تأثیر تغییرات را توضیح دهد.
• از نسخه‌بندی معنایی استفاده کنید: هنگام تعیین افزایش نسخه مناسب برای هر پکیج، از اصول نسخه‌بندی معنایی پیروی کنید. این به کاربران پکیج‌های شما کمک می‌کند تا به راحتی تأثیر هر انتشار را درک کنند.
• فرآیند انتشار را خودکار کنید: Changesets را با پایپ‌لاین CI/CD خود یکپارچه کنید تا فرآیند انتشار را خودکار کنید. این کار خطر خطای انسانی را کاهش داده و از نسخه‌بندی یکپارچه در تمام پکیج‌ها اطمینان حاصل می‌کند.
• تغییرنامه‌ها را با دقت بازبینی کنید: قبل از ادغام تغییرنامه‌ها در شاخه اصلی، آنها را با دقت بازبینی کنید. این به شناسایی خطاها و اطمینان از مستندسازی صحیح تغییرات کمک می‌کند.
• تغییرنامه‌ها را کوچک و متمرکز نگه دارید: سعی کنید تغییرنامه‌های کوچک و متمرکزی ایجاد کنید که به یک مسئله یا ویژگی واحد بپردازند. این کار درک و بازبینی تغییرات را آسان‌تر می‌کند.

مثال‌های دنیای واقعی

بسیاری از کتابخانه‌ها و فریمورک‌های محبوب جاوااسکریپت از تغییرنامه‌های فرانت‌اند برای مدیریت نسخه‌بندی و انتشارها استفاده می‌کنند. در اینجا چند مثال آورده شده است:

• React Aria: کتابخانه‌ای از کامپوننت‌های React برای ساخت رابط‌های کاربری قابل دسترس.
• Reach UI: کتابخانه‌ای از اجزای اولیه رابط کاربری قابل دسترس برای React.
• بسیاری از پروژه‌های متن‌باز دیگر: پروژه‌های متعدد دیگری از Changesets به دلیل فرآیند انتشار ساده و ویژگی‌های همکاری بهبودیافته‌اش استفاده می‌کنند.

این پروژه‌ها با موفقیت Changesets را برای بهبود فرآیند انتشار، افزایش همکاری و حفظ سابقه شفافی از تغییرات به کار گرفته‌اند. تجربیات آنها ارزش و تطبیق‌پذیری این ابزار قدرتمند را نشان می‌دهد.

عیب‌یابی مشکلات رایج

در حالی که استفاده از Changesets به طور کلی ساده است، ممکن است با برخی مشکلات رایج مواجه شوید. در اینجا چند نکته برای عیب‌یابی آورده شده است:

• `No changesets found`: این خطا معمولاً نشان می‌دهد که شما هیچ تغییرنامه‌ای ایجاد نکرده‌اید یا Changesets به درستی پیکربندی نشده است. اطمینان حاصل کنید که حداقل یک تغییرنامه ایجاد کرده‌اید و فایل `config.json` به درستی پیکربندی شده است.
• `Version conflict`: این خطا زمانی رخ می‌دهد که دو یا چند تغییرنامه، افزایش نسخه‌های متناقضی را برای یک پکیج مشخص کنند. تغییرنامه‌ها را بازبینی کرده و از سازگاری آنها اطمینان حاصل کنید.
• `Publish failed`: این خطا می‌تواند به دلایل مختلفی رخ دهد، مانند اعتبارنامه‌های نادرست npm یا مشکلات اتصال به شبکه. اعتبارنامه‌های npm خود را بررسی کرده و از داشتن اتصال اینترنت پایدار اطمینان حاصل کنید.
• مشکلات یکپارچه‌سازی CI/CD: پیکربندی CI/CD خود را با دقت بازبینی کنید و اطمینان حاصل کنید که متغیرهای محیطی لازم (مانند `GITHUB_TOKEN`، `NPM_TOKEN`) به درستی تنظیم شده‌اند و دستورات Changesets به ترتیب صحیح اجرا می‌شوند.

اگر با هر مشکل دیگری مواجه شدید، به مستندات رسمی Changesets مراجعه کنید یا از جامعه Changesets کمک بگیرید.

نتیجه‌گیری

تغییرنامه‌های فرانت‌اند یک راهکار قدرتمند و انعطاف‌پذیر برای مدیریت نسخه‌بندی و انتشارها در پروژه‌های فرانت‌اند ارائه می‌دهند. با خودکارسازی فرآیند انتشار، ساده‌سازی همکاری و افزایش شفافیت، Changesets می‌تواند به طور قابل توجهی کارایی و قابلیت اطمینان گردش کار توسعه شما را بهبود بخشد. چه بر روی یک پروژه شخصی کوچک کار می‌کنید یا یک اپلیکیشن سازمانی در مقیاس بزرگ، Changesets می‌تواند به شما در مدیریت مؤثرتر کدبیس و ارائه نرم‌افزار با کیفیت بالا به کاربران‌تان کمک کند.

با پیروی از دستورالعمل‌ها و بهترین شیوه‌های ذکر شده در این راهنما، می‌توانید بر تغییرنامه‌های فرانت‌اند مسلط شوید و از پتانسیل کامل آن برای بهبود گردش کار توسعه فرانت‌اند خود بهره‌مند شوید. Changesets را بپذیرید و امروز کنترل مدیریت نسخه خود را به دست بگیرید!