ترحيلات التوثيق

هذا نوع الملف الذي يكتبه وكيل البرمجة حين يوثّق ميزة جديدة، ويحدّث صفحة ذات صلة، ويضيف الصفحة الجديدة إلى التنقل:

<?php

use LaRecipe\Migrations\DocsMigration;

return new class extends DocsMigration
{
    protected string $set = 'handbook';

    protected string $author = 'claude-code';

    protected string $ref = '';

    protected string $summary = 'Document CSV exports';

    public function up(): void
    {
        $this->createPage('3.x/billing/exports', frontmatter: [
            'title' => 'CSV exports',
            'description' => 'Export invoices as a CSV file from the billing page.',
            'sources' => ['app/Billing/Exports/**'],
        ], body: <<<'MD'
            # CSV exports

            Open **Billing**, then choose **Export as CSV**.
            MD);

        $this->updatePage('3.x/billing/invoices', basedOn: 'sha256:9f3a2c…', frontmatter: [
            'title' => 'Invoices',
            'description' => 'Find, download and export your invoices.',
            'sources' => ['app/Billing/**'],
        ], body: <<<'MD'
            # Invoices

            Every invoice is on the billing page. To get them all at once, export them as CSV.
            MD);

        $this->updateNavigation('3.x', basedOn: 'sha256:51be07…', patch: [
            [
                'add' => 'billing/exports',
                'group' => 'Billing',
                'after' => 'billing/invoices',
            ],
        ]);
    }
};

البصمات مختصرة هنا؛ أما البصمة الحقيقية فهي sha256: يليها 64 حرفًا ست عشريًا. ومتون الصفحات نصوص nowdoc مُزاحة مع الكود، فيُقرأ فرق الـ pull request كأنه Markdown. ويزيل PHP إزاحة علامة الإغلاق من كل سطر، فتحصل الصفحة على Markdown الذي تراه بالضبط.

يوسّع LaRecipe\Migrations\DocsMigration الصنف Migration في Laravel. وأربع خصائص تصف التغيير:

داخل up() تستدعي العمليات. وكل منها يأخذ عنوان صفحة: 3.x/billing/exports في مجموعة ذات إصدارات، و 3.x/ar/billing/exports لصفحة بلغة أخرى، و billing/exports في مجموعة بلا إصدارات.

تمر كل عملية عبر مسار الكتابة نفسه الذي يمر فيه أي تغيير آخر في مجموعة قاعدة البيانات، بوصفها ترحيلًا مع $author و $ref الخاصين بك. ويُتحقق منها: المحتوى الذي فيه أخطاء تحقق، أو العنوان غير الموجود في المجموعة، يُفشل الترحيل، فيلتقط CI الترحيل المعطّل قبل أن تلتقطه عملية النشر. وتُنشر فورًا: فالـ pull request كان هو المراجعة، في كلا وضعي المراجعة.

تعيش ترحيلات التوثيق في database/migrations/docs/، داخل مجلد الترحيلات في تطبيقك لكن منفصلة عن ترحيلات المخطط، فيعرض الـ pull request النوعين منفصلين. غيّر المجلد عبر migrations.path:

'migrations' => [
    'path' => database_path('migrations/docs'),
    'skip_in_tests' => false,
],

حين تستخدم أي مجموعة مصدر قاعدة البيانات، يسجّل LaRecipe هذا المجلد لدى أداة الترحيل في Laravel. وكل عملية نشر تشغّل php artisan migrate أصلًا، فلا خطوة جديدة: migrate:status و migrate:rollback و migrate --path=database/migrations/docs تعمل كما مع أي ترحيل. وترحيل التوثيق لمجموعة لم تعد تستخدم مصدر قاعدة البيانات يُتخطّى ويبقى معلّقًا.

ملف واحد لكل فرع، يحمل اسمه: على feature/csv-exports يكون database/migrations/docs/2026_10_17_141502_docs_feature_csv_exports.php. والمجموعة غير الافتراضية تضيف مفتاحها: ..._docs_handbook_feature_csv_exports.php. وخارج أي فرع git، ينتهي الاسم بـ local. وتذكر نتيجةُ كل أداة تأليف الملفَّ في docs_migration.

يُعاد كتابة الملف مع تقدّم الجلسة، فيحمل الـ pull request ملفًا واحدًا مقروءًا بدلًا من عشرات الملفات. والتغييرات على الصفحة نفسها تُدمج معًا: الإنشاء ثم التحديث يصبحان createPage واحدًا، والتحديثان يصبحان updatePage واحدًا يحتفظ بأول basedOn، والإنشاء ثم الحذف لا يتركان شيئًا (ويختفي الملف حين يصبح فارغًا). ويُسمّى المؤلف باسم عميل MCP، ويجمع الملخّصُ ملخّصَ كل استدعاء في سطر واحد.

يُسجَّل الملف في جدول الترحيلات المحلي لديك على أنه شُغّل من قبل، فلا يطبّقه php artisan migrate المحلي مرتين، ويتراجع php artisan migrate:rollback المحلي عن الجلسة. وتطلب المهارتان larecipe-write-docs و larecipe-update-docs من الوكلاء أن يضيفوه في commit مع الكود.

basedOn هي بصمة المحتوى الذي كُتب التغيير بناءً عليه. تملؤها أدوات الوكيل من قاعدة بياناتك المحلية (يقرأ الوكيل الصفحة بالأداة read_page، التي تعيد content_hash الخاص بها، ويمرّره بوصفه based_on)، ويملؤها larecipe:make:docs-migration من المجموعة. وعند النشر، قبل كل تحديث أو نقل أو حذف أو تغيير في التنقل أو ملف التعريف، يقارنها LaRecipe بما هو حي. فإن تغيّر الإنتاج في الأثناء:

• يُحفظ التغيير مراجعةً بالحالة conflict، تحمل نسخة الترحيل بجوار نسخة الإنتاج، في أعلى قائمة المراجعة في لوحة الإدارة، حيث يبقي شخصٌ على الإنتاج، أو يأخذ الترحيل، أو يحرّر دمجًا بينهما.
• يُطلق الحدث DocsMigrationConflicted.
• يطبع php artisan migrate تحذيرًا ويتابع:

WARN LaRecipe docs conflict: [3.x/billing/invoices] The page [billing/invoices] changed since this change was written (expected sha256:9f3a2c…, found sha256:e41b07…). Kept as a conflict draft for review.

و createPage على مسار فيه صفحة أصلًا تعارضٌ أيضًا. والعملية التي بلا basedOn تتخطّى الفحص وتكتب فوق المحتوى، فأبقِ basedOn في مكانه.

يشغّل php artisan migrate:rollback الدالة down() المدمجة. فتمرّ على عمليات الترحيل بالعكس وتعيد كل واحدة بوصفها مراجعة جديدة: الصفحة المستبدلة تستعيد نسختها السابقة، والصفحة المنشأة تُزال، والصفحة المحذوفة تعود.

ولا يدهس التراجع تعديلًا لاحقًا أبدًا أيضًا. فإن غيّر أحدٌ صفحة بعد تشغيل الترحيل، تحتفظ الصفحة بذلك التعديل، وتنتظر نسخة التراجع مسودةَ تعارض، ويبلّغ التراجع عنها. أما التعارض الذي أثاره الترحيل ولم يحلّه أحد فيُرفض.

في مجموعة اختبارات تطبيقك، تعمل ترحيلات التوثيق كأي ترحيل آخر؛ فهي عمليات إدراج صغيرة. ولتتخطّاها، اضبط migrations.skip_in_tests على true: فأثناء تشغيل الاختبارات تُتخطّى ترحيلات التوثيق وتبقى معلّقة.