نام (NAME)

deb-changelog - پرونده گزارش تغییرات بسته‌های منبع دبیان

خلاصه دستور (SYNOPSIS)

debian/changelog

توضیحات (DESCRIPTION)

تغییرات در نگارش بسته‌بندی‌شده یک پروژه در پرونده گزارش تغییرات debian/changelog توضیح داده می‌شوند. این مورد شامل اصلاحات انجام‌شده در بسته منبع در مقایسه با نگارش بالادستی (upstream) و همچنین سایر تغییرات و به‌روزرسانی‌های بسته است.

قالب debian/changelog به ابزارهای ساخت بسته اجازه می‌دهد دریابند کدام نگارش از بسته در حال ساخت است و اطلاعات اختصاصی دیگر انتشار را به دست آورند.

این قالب مجموعه‌ای از مدخل‌ها به این شکل است:

package (version) distributions; metadata
         [خط(های) خالی اختیاری، حذف می‌شوند]
 * change-details
   more-change-details
         [خط(های) خالی، در خروجی dpkg-parsechangelog(1) گنجانده می‌شوند]
 * even-more-change-details
         [خط(های) خالی اختیاری، حذف می‌شوند]
 -- maintainer-name <email-address>  date

package و version نام بسته منبع و شماره نگارش آن هستند. version بین پرانتزهای U+0028 ‘(’ و U+0029 ‘)’ محدود شده است.

distributions یک یا چند توزیع جداشده با فاصله را فهرست می‌کند که این نگارش هنگام بارگذاری (upload) باید در آن‌ها نصب شود؛ این مقدار به فیلد Distribution در پرونده .changes کپی می‌شود. distributions باید با یک نقطه-ویرگول (سیکولون، U+003B ‘;’) خاتمه یابد.

metadata صفر یا چند مورد keyword=value جداشده با کاما را فهرست می‌کند. هر کلیدواژه فقط می‌تواند شامل علامت منها و نویسه‌های الفبایی-عددی بدون حساسیت به حروف کوچک و بزرگ باشد، زیرا باید به نام‌های فیلد deb822(5) نگاشت شوند. تنها keywordهایی که در حال حاضر توسط dpkg پشتیبانی می‌شوند عبارتند از:

urgency: مقدار آن برای فیلد Urgency در پرونده .changes هنگام بارگذاری استفاده می‌شود.
binary-only: با مقدار yes، برای نشان دادن این موضوع استفاده می‌شود که این مدخل گزارش تغییرات مربوط به یک بارگذاری غیرنگهدارنده صرفاً دودویی (binary-only non-maintainer upload) است (یک بازساخت خودکار دودویی که تنها تغییر آن خود مدخل گزارش تغییرات است).

جزئیات تغییرات در واقع می‌تواند هر مجموعه‌ای از خطوط باشد که با دست‌کم دو فاصله (U+0020 SPACE) شروع می‌شوند، اما به صورت قراردادی هر تغییر با یک علامت ستاره و یک فاصله جداکننده آغاز می‌شود و خط‌های ادامه‌دار به گونه‌ای تورفتگی پیدا می‌کنند که با شروع متن بالاتر تراز شوند. در صورت تمایل می‌توان از خط‌های خالی برای جداسازی گروه‌های تغییرات استفاده کرد.

اگر این بارگذاری باگ‌های ثبت‌شده در سامانه پیگیری باگ توزیع را برطرف کند، ممکن است با گنجاندن رشته زیر در جزئیات تغییرات:

Closes: #nnnnn

با گنجانده شدن این بسته در بایگانی توزیع، باگ‌ها به طور خودکار بسته شوند، که در آن #nnnnn شماره باگ است. عبارت باقاعده (regex) دقیق پرل به شرح زیر است:

/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i

به بیان دیگر، این رشته باید شامل واژه closes: به همراه فهرستی از شماره‌های باگ جداشده با کاما باشد. شماره‌های باگ ممکن است با کلمه bug یا علامت # شروع شوند، مانند "Closes: 42, bug#43, #44, bug 45". واژه‌های closes: و bug به بزرگی و کوچکی حروف حساس نیستند. فهرست شماره‌های باگ می‌تواند چند خط را در بر بگیرد.

این اطلاعات از طریق فیلد Closes در پرونده .changes منتقل می‌شود. در آنجا، بسته به نرم‌افزار مدیریت بایگانی، تمام شماره باگ‌های فهرست‌شده ممکن است به طور خودکار بسته شوند.

نام و نشانی رایانامه نگه‌دارنده که در گزارش تغییرات استفاده می‌شود باید مشخصات فردی باشد که این انتشار از بسته را آماده کرده است. این اطلاعات الزماً نه مشخصات بارگذار است و نه نگه‌دارنده همیشگی بسته. اطلاعات موجود در اینجا در فیلد Changed-By در پرونده .changes کپی خواهد شد، و ممکن است بعداً هنگام نصب بارگذاری در بایگانی توزیع، برای ارسال پیام تایید و وصول استفاده شود.

متغیر date دارای قالب زیر است (سازگار و با همان بار معنایی RFC2822 و RFC5322، یا آنچه دستور «date -R» تولید می‌کند):

day-of-week, dd month yyyy hh:mm:ss +zzzz

که در آن:

day-of-week: یکی از این موارد است: Mon، Tue، Wed، Thu، Fri، Sat، Sun.
dd: روز یک یا دو رقمی ماه (01-31) است که صفر آغازین اختیاری است، اما به صورت سنتی حذف نمی‌شود.
month: یکی از این موارد است: Jan، Feb، Mar، Apr، May، Jun، Jul، Aug، Sep، Oct، Nov، Dec.
yyyy: سال چهار رقمی است (مانند 2010).
hh: ساعت دو رقمی است (00-23).
mm: دقیقه دو رقمی است (00-59).
ss: ثانیه دو رقمی است (00-60).
[+-]zzzz: اختلاف منطقه زمانی نسبت به زمان هماهنگ جهانی (UTC) است. علامت ‘+’ نشان می‌دهد زمان جلوتر از UTC (یعنی شرق آن) است و ‘-’ نشان می‌دهد زمان عقب‌تر از UTC (یعنی غرب آن) است. دو رقم اول اختلاف ساعت نسبت به UTC و دو رقم آخر دقایق اضافی اختلاف نسبت به UTC را نشان می‌دهند. دو رقم آخر باید در بازه 00-59 باشند.

نخستین خط «عنوان» (title) با نام بسته باید دقیقاً از حاشیه سمت چپ آغاز شود. پیش از خط «پایانی» (trailer) حاوی مشخصات نگه‌دارنده و تاریخ، باید دقیقاً یک فاصله (U+0020 SPACE) قرار گیرد. مشخصات نگه‌دارنده و تاریخ باید دقیقاً با دو فاصله (U+0020 SPACE) از یکدیگر جدا شوند. هر بخش از date می‌تواند با یک یا چند فاصله (U+0020 SPACE) جدا شود، به‌جز پس از کاما که می‌تواند با صفر یا چند فاصله (U+0020 SPACE) جدا شود.

هر خطی که به طور کامل (یعنی بدون هیچ فاصله آغازین) متشکل از نماد # یا یادداشت‌های به شیوه /* */ یا کلیدواژه‌های RCS باشد باید نادیده گرفته شود.

خطوط modeline در Vim یا متغیرهای محلی Emacs، و مدخل‌های قدیمی گزارش تغییرات با قالب‌های دیگر در انتهای پرونده باید پذیرفته شده و در خروجی حفظ شوند، اما ممکن است محتوای آن‌ها در غیر این صورت نادیده گرفته شود و تجزیه پرونده در آن نقطه متوقف شود.

کل پرونده گزارش تغییرات باید با کدگذاری UTF-8 باشد.

فایل‌ها (FILES)

debian/changelog

مثال‌ها (EXAMPLES)

dpkg (1.17.18) unstable; urgency=low
 [ Guillem Jover ]
 * Handle empty minimum versions when initializing dependency versions,
   as the code is mapping the minimum version 0 to '' to avoid outputting
   useless versions. Regression introduced in dpkg 1.17.17. Closes: #764929
 [ Updated programs translations ]
 * Catalan (Guillem Jover).
 [ Updated dselect translations ]
 * Catalan (Guillem Jover).
 * German (Sven Joachim).
 -- Guillem Jover <guillem@debian.org>  Sun, 12 Oct 2014 15:47:44 +0200

همچنین ببینید (SEE ALSO)

deb822(5), deb-changes(5), deb-version(7), dpkg-parsechangelog(1).