# دليل إدارة المستودع وبروتوكولات العمل على GitHub (Git / GitHub Operations Guide) يوفر هذا الملف إطار العمل الشامل والقياسي (Standard Operating Procedures) لإدارة مستودع **ستيجانو بكسل (SteganoPixel)** على منصة GitHub. يهدف هذا الدليل إلى توحيد جهود المطورين، تنظيم المساهمات البرمجية، وضمان أعلى مستويات الجودة والأمان خلال دورة حياة التطوير. --- ## 1. إعدادات المستودع الموصى بها على GitHub (Repository Configuration) لضمان أمان الشفرة المصدرية وسلاسة العمل الجماعي، يُوصى بتطبيق الإعدادات التالية في لوحة تحكم المستودع (`Settings`): ### أ. البيانات الوصفية والهوية (Metadata & Topics) * **اسم المستودع:** `steganopixel` * **الوصف (Description):** > SteganoPixel 🎨 - Advanced Client-Side LSB Steganography Web Application in Arabic for Embedding, Extracting, and Sanitizing Hidden Texts in Digital Images. * **الوسوم (Topics / Tags):** `steganography`, `lsb-steganography`, `react`, `tailwind-css`, `typescript`, `vite`, `image-processing`, `security`, `privacy`, `arabic-web-app` * **الموقع الرسمي (Website):** رابط الاستضافة المباشر (مثل `https://steganopixel.vercel.app` أو `https://your-username.github.io/steganopixel`). ### ب. قواعد حماية الفروع (Branch Protection Rules) يجب تفعيل حماية صارمة على الفرعين المحوريين `main` و `develop`: 1. **Require a pull request before merging:** منع الدفع المباشر (`Direct Push`) إلى هذه الفروع. 2. **Require approvals:** اشتراط موافقة مطور واحد على الأقل (`1 Approver`) قبل دمج أي Pull Request. 3. **Require status checks to pass before merging:** اشتراط اجتياز خط أنابيب التجميع والاختبار (`SteganoPixel CI/CD Pipeline`) بنجاح. 4. **Require conversation resolution:** اشتراط حل جميع الملاحظات والتعليقات البرمجية قبل الدمج. 5. **Do not allow bypassing the above settings:** تطبيق هذه القواعد على جميع المطورين، بما في ذلك مديري المستودع (Admins). --- ## 2. استراتيجية إدارة الفروع (Branching Strategy / GitFlow) يعتمد المشروع على نموذج **GitFlow** المنظم. يتم تصنيف الفروع حسب الغرض منها لضمان عدم تداخل التعديلات: ```text main ──*─────────────────────────────────────*── (Production Releases) \ / develop *──────*─────────────*────────────*──── (Staging / Integration) \ / / feature/* *─────────* / (New Features / Sub-tasks) / hotfix/* *──────── (Urgent Production Bug Fixes) ``` | نوع الفرع | التسمية القياسية | مشتق من | يُدمج إلى | الغرض | | :--- | :--- | :--- | :--- | :--- | | **الإنتاج (Production)** | `main` | — | — | يحتوي دائماً على الشفرة المستقرة والجاهزة للمستخدمين النهائيين. كل دمج هنا يقابله إصدار (Release). | | **التطوير (Integration)** | `develop` | `main` | `main` | الفرع المحوري المجمع للميزات الجديدة. يُستخدم للاختبار الشامل قبل النقل للإنتاج. | | **الميزات (Features)** | `feature/` | `develop` | `develop` | لتطوير ميزة أو صفحة جديدة (مثلاً: `feature/confetti-animation` أو `feature/pdf-support`). | | **الإصلاحات (Bug Fixes)** | `bugfix/` | `develop` | `develop` | لإصلاح أخطاء غير حرجة تم اكتشافها أثناء التطوير (مثلاً: `bugfix/download-button-mobile`). | | **الطوارئ (Hotfixes)** | `hotfix/`| `main` | `main` و `develop`| لإصلاح أخطاء حرجة جداً في الإنتاج بشكل فوري (مثلاً: `hotfix/lsb-overflow-crash`). | --- ## 3. اصطلاحات كتابة رسائل الالتزام (Conventional Commits) يعتمد المشروع اصطلاحات الالتزام القياسية العالمية (**Conventional Commits**) لضمان قراءة تاريخ التعديلات بوضوح وتوليد سجل التغييرات (`CHANGELOG.md`) تلقائياً. ### الهيكل القياسي: ```text (): ``` ### أنواع الالتزامات المعتمدة (`Types`): | النوع | المعنى | مثال قياسي بالإنجليزية | | :--- | :--- | :--- | | **`feat`** | إضافة ميزة برمجية أو وظيفية جديدة | `feat(steganography): add web worker for asynchronous embedding` | | **`fix`** | إصلاح خطأ برمجي أو بصري | `fix(ui): resolve blob download link issue on mobile browsers` | | **`docs`** | تعديل أو إضافة ملفات التوثيق | `docs(customization): update font replacement instructions` | | **`style`** | تعديلات شكلية لا تؤثر على المنطق (مسافات، فواصل) | `style(components): reformat UploadCard component syntax` | | **`refactor`** | إعادة هيكلة الكود دون إضافة ميزة أو إصلاح خطأ | `refactor(engine): separate bit reading logic into utility fn` | | **`perf`** | تحسينات ترفع من أداء وسرعة التطبيق | `perf(canvas): use requestAnimationFrame to prevent ui freeze` | | **`test`** | إضافة اختبارات آلية جديدة أو تعديل الحالية | `test(engine): add exhaustive suite for LSB 3-channel encode` | | **`build`** | تعديلات على أدوات التجميع أو الحزم (`npm`, `Vite`) | `build(vite): configure static asset inline limit` | | **`ci`** | تعديلات على إعدادات GitHub Actions | `ci(workflow): set output artifact retention days to 7` | ### قواعد هامة لكتابة الالتزام: 1. يجب كتابة الالتزام باللغة **الإنجليزية** لضمان التوافق العالمي. 2. يجب أن يبدأ الموضوع فعل أمر بصيغة المضارع (مثال: `add` وليس `added` أو `adds`). 3. ألا يتجاوز السطر الأول `72` حرفاً. --- ## 4. بروتوكول طلبات الدمج والمراجعة (Pull Request & Code Review) لتقديم مساهمة برمجية ناجحة، يُرجى الالتزام بالبروتوكول التالي عند إنشاء طلب دمج (**Pull Request**): 1. **تحديث الفرع المحلي:** تأكد من عمل `git pull origin develop` ودمج أحدث التغييرات في فرعك قبل إنشاء الـ PR. 2. **العنوان القياسي:** استخدم نفس صيغة الالتزامات (مثال: `feat(ui): implement success confetti animations`). 3. **استخدام قالب طلب الدمج:** انسخ واملأ القالب التالي في صندوق وصف الـ PR: ```markdown ### 🎯 ملخص التغييرات (Summary of Changes) - [شرح مختصر لما تم إضافته أو إصلاحه في هذا الـ PR] ### 🔗 التذكرة المتصلة (Related Issue) - يغلق تذكرة رقم: #123 ### 📋 قائمة التحقق (Checklist) - [ ] تم اختبار التغييرات محلياً على أكثر من متصفح (Chrome, Firefox). - [ ] الكود خالي من تعليقات الـ `console.log` والـ `TODO` المنسية. - [ ] تم الالتزام بأفضل ممارسات الـ TypeScript (عدم استخدام `any`). - [ ] تمت إضافة تعليقات توضيحية كاملة لأي جزء منطقي معقد. ### 🖼️ لقطات شاشة / معاينة (Screenshots / Before & After) | قبل (Before) | بعد (After) | | :---: | :---: | | [ضع صورة هنا إن وجد] | [ضع صورة هنا إن وجد] | ``` --- ## 5. إدارة الإصدارات والوسوم (Semantic Versioning - SemVer) نتبع في **SteganoPixel** معيار التقسيم الدلالي للإصدارات (**SemVer: `MAJOR.MINOR.PATCH`**): * **`MAJOR` (الإصدار الرئيسي):** تغييرات جذرية غير متوافقة مع الإصدارات السابقة (مثلاً: تغيير خوارزمية التشفير من LSB إلى خوارزمية DCT معمارية). * **`MINOR` (الإصدار الفرعي):** إضافات وظائف جديدة متوافقة مع الإصدارات السابقة (مثلاً: إضافة خيار حماية النص بكلمة مرور). * **`PATCH` (الإصدار التصحيحي):** إصلاحات أخطاء أو تحسينات أداء طفيفة (مثلاً: إصلاح مشكلة تنزيل الصورة في متصفح سفاري). ### كيفية إطلاق إصدار جديد (Releasing Protocol): 1. قم بإنشاء فرع إصدار مشتق من `develop` (مثال: `release/v1.1.0`). 2. حدّث رقم الإصدار في `package.json`. 3. ادمج الفرع إلى `main` وإلى `develop`. 4. قم بإنشاء وسم Git Tag على الفرع `main`: ```bash git tag -a v1.1.0 -m "Release v1.1.0: Enhanced performance and new preview tools" git push origin v1.1.0 ``` 5. توجّه إلى صفحة **Releases** في GitHub وأطلق الإصدار رسمياً مع إرفاق سجل التغييرات (`Changelog`). --- ## 6. قوالب الإبلاغ عن الأخطاء والميزات (GitHub Issue Templates) لتسهيل إدارة المهام، يُنصح بتفعيل مجلد `.github/ISSUE_TEMPLATE` أو الاعتماد على القوالب التالية عند فتح `Issue` جديدة: ### أ. قالب الإبلاغ عن خطأ (Bug Report Template) ```markdown **عنوان التذكرة:** [Bug]: وصف مختصر للخطأ **وصف الخطأ:** [اشرح الخطأ بالتفصيل وما الذي حدث خلافاً للمتوقع] **خطوات إعادة التكرار (Steps to Reproduce):** 1. اذهب إلى صفحة '...' 2. ارفع صورة من نوع '...' 3. اضغط على زر '...' 4. شاهد الخطأ **السلوك المتوقع (Expected Behavior):** [ما الذي كان يفترض أن يحدث؟] **البيئة (Environment):** - نظام التشغيل: [مثال: Windows 11 / macOS 14] - المتصفح وإصداره: [مثال: Chrome 122] - حجم الصورة ونوعها: [مثال: 5MB PNG] ``` ### ب. قالب طلب ميزة (Feature Request Template) ```markdown **عنوان التذكرة:** [Feature]: اسم الميزة المقترحة **المشكلة التي تحلها الميزة:** [اشرح الصعوبة أو المشكلة الحالية التي تواجه المستخدمين] **الحل المقترح (Proposed Solution):** [اشرح كيف ستعمل الميزة الجديدة وكيف ستعزز من قدرات التطبيق] **بدائل تم التفكير فيها (Alternatives Considered):** [أي طرق أخرى فكرت فيها لحل المشكلة] ``` --- ## 7. الأتمتة المدمجة (GitHub Actions CI/CD Pipeline) يحتوي المستودع على خط أنابيب مؤتمت بالكامل معرّف في `.github/workflows/ci.yml`. يعمل هذا الخط تلقائياً عند أي عملية `push` أو `pull_request` على فروع التطوير والإنتاج لضمان الجودة. ### المهام التي ينفذها خط الأنابيب (CI Workflow): 1. **التحقق من التنسيق (Linting):** فحص الكود والتأكد من خلوه من الأخطاء البنيوية. 2. **فحص التنميط (Type Checking):** تشغيل مترجم `TypeScript` الصارم لضمان عدم وجود تناقض في الأنواع. 3. **تجميع الإنتاج (Production Build):** تنفيذ الأمر `npm run build` للتأكد من أن تطبيق `Vite` قادر على تحويل الكود بالكامل إلى مجلد `dist/` سليم. 4. **حفظ المخرجات (Artifacts):** حفظ المخرجات النهائية المجمعة لمدة 7 أيام ليتمكن المطورون من تنزيلها وفحصها.