Mohamed-Abdelhalim2
18a0a089b6
Signed-off-by: Mohamed-Abdelhalim2 <codepen.io.dropper985@passinbox.com>
186 أسطر
12 KiB
Markdown
186 أسطر
12 KiB
Markdown
# دليل إدارة المستودع وبروتوكولات العمل على 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/<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`) تلقائياً.
|
|
|
|
### الهيكل القياسي:
|
|
```text
|
|
<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:
|
|
|
|
```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 أيام ليتمكن المطورون من تنزيلها وفحصها.
|