Mohamed-Abdelhalim2/steganopixel
1
0
نسخ 0
الشفرة المشكلات طلبات السحب Actions Packages المشاريع الإصدارات 1 الويكي النشاط
الملفات
develop
steganopixel/GIT.md
Mohamed-Abdelhalim2 18a0a089b6 الملفات الأساسية 
Signed-off-by: Mohamed-Abdelhalim2 <codepen.io.dropper985@passinbox.com>
2026-06-16 22:47:25 +00:00

12 KiB
خام الرابط الدائم اللوم التاريخ

دليل إدارة المستودع وبروتوكولات العمل على 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 المنظم. يتم تصنيف الفروع حسب الغرض منها لضمان عدم تداخل التعديلات:

  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/<name> develop develop لتطوير ميزة أو صفحة جديدة (مثلاً: feature/confetti-animation أو feature/pdf-support).
الإصلاحات (Bug Fixes) bugfix/<ticket> develop develop لإصلاح أخطاء غير حرجة تم اكتشافها أثناء التطوير (مثلاً: bugfix/download-button-mobile).
الطوارئ (Hotfixes) hotfix/<ticket> main main و develop لإصلاح أخطاء حرجة جداً في الإنتاج بشكل فوري (مثلاً: hotfix/lsb-overflow-crash).

3. اصطلاحات كتابة رسائل الالتزام (Conventional Commits)

يعتمد المشروع اصطلاحات الالتزام القياسية العالمية (Conventional Commits) لضمان قراءة تاريخ التعديلات بوضوح وتوليد سجل التغييرات (CHANGELOG.md) تلقائياً.

الهيكل القياسي:

<type>(<scope>): <subject>

<body>

أنواع الالتزامات المعتمدة (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:
### 🎯 ملخص التغييرات (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: 
    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)

**عنوان التذكرة:** [Bug]: وصف مختصر للخطأ

**وصف الخطأ:**
[اشرح الخطأ بالتفصيل وما الذي حدث خلافاً للمتوقع]

**خطوات إعادة التكرار (Steps to Reproduce):**
1. اذهب إلى صفحة '...'
2. ارفع صورة من نوع '...'
3. اضغط على زر '...'
4. شاهد الخطأ

**السلوك المتوقع (Expected Behavior):**
[ما الذي كان يفترض أن يحدث؟]

**البيئة (Environment):**
- نظام التشغيل: [مثال: Windows 11 / macOS 14]
- المتصفح وإصداره: [مثال: Chrome 122]
- حجم الصورة ونوعها: [مثال: 5MB PNG]

ب. قالب طلب ميزة (Feature Request Template)

**عنوان التذكرة:** [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 أيام ليتمكن المطورون من تنزيلها وفحصها.