دليل المساهمة

المساهمة في ماسح DuoKey PQC

دليل للمساهمة في تطوير ماسح DuoKey PQC

ينطبق على:

Rust DevelopmentOpen SourceCommunity

شكرًا لاهتمامك بالمساهمة في ماسح DuoKey PQC! سيساعدك هذا الدليل على البدء في التطوير.

إعداد التطوير

المتطلبات المسبقة

المتطلبات المسبقة

• Rust: سلسلة الأدوات المستقرة (يُوصى بأحدث إصدار)
• Git: للتحكّم في الإصدارات
• بيئة التطوير المتكاملة: VS Code مع إضافة rust-analyzer (موصى بها)

استنساخ المستودع

git clone https://github.com/duokey/dke-scanner-agent.git
cd dke-scanner-agent

تثبيت التبعيات

# Install Rust if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update Rust to latest stable
rustup update stable

# Install development tools
rustup component add rustfmt clippy

# Install cargo-watch for development
cargo install cargo-watch

# Install cargo-audit for security checks
cargo install cargo-audit

بناء المشروع

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- agent

بنية المشروع

على مستوى عالٍ، يُنظَّم المشروع في المجالات الوظيفية التالية:

المجال	المحتويات
واجهة سطر الأوامر	واجهة سطر الأوامر وإرسال الأوامر
الأساسي	منطق المسح الأساسي -- اكتشاف التشفير، وتسجيل المخاطر، وعمليات X.509، وقاعدة بيانات الخوارزميات
الماسحات	أوضاع المسح -- الوكيل، ونظام الملفات، والنطاق، والشبكة
المحلِّلات	محلِّلات الصيغ لصيغ الشهادات ومخازن المفاتيح المدعومة
المخرجات	مُنسِّقات المخرجات لصيغ التقارير المدعومة
الأدوات المساعدة	مساعِدات مشتركة مثل التسجيل ومعالجة الأخطاء
الاختبارات	اختبارات التكامل
معايير القياس	معايير قياس الأداء
الأمثلة	أمثلة الاستخدام

سير عمل التطوير

1

إنشاء فرع الميزة

git checkout -b feature/my-new-feature

2

إجراء التغييرات

# Edit code in your preferred editor

# Format code
cargo fmt

# Run clippy for lints
cargo clippy -- -D warnings

# Run tests
cargo test

# Run specific test
cargo test test_rsa_detection

3

الاختبار محليًا

# Run all tests
cargo test --all

# Run integration tests
cargo test --test '*'

# Run with coverage (requires cargo-tarpaulin)
cargo install cargo-tarpaulin
cargo tarpaulin --out Html

# Run benchmarks
cargo bench

4

تأكيد التغييرات

git add .
git commit -m "feat: add new feature"

5

الدفع وإنشاء طلب سحب

git push origin feature/my-new-feature
# Create pull request on GitHub

معايير كتابة الكود

دليل أسلوب Rust

اتبع إرشادات واجهة برمجة تطبيقات Rust. فضّل الأسماء الوصفية الواضحة بذاتها للدوال والأنواع، ووثّق كل عنصر عام بتعليق توثيقي يشرح غرضه. تجنّب الأسماء المختصرة والغامضة وواجهات برمجة التطبيقات العامة غير الموثّقة.

تنسيق الكود

استخدم rustfmt بالإعدادات الافتراضية:

cargo fmt

يثبّت ملف rustfmt.toml الخاص بالمشروع إصدار 2021، ويضبط أقصى عرض للسطر عند 100 حرف، ويستخدم إعداد small-heuristics الافتراضي.

الفحص اللغوي

استخدم clippy للفحص اللغوي:

cargo clippy -- -D warnings

التوثيق

وثّق جميع واجهات برمجة التطبيقات العامة بتعليقات توثيقية. يلخّص التعليق التوثيقي الجيد ما يفعله العنصر ويتضمّن الأقسام القياسية حيثما كان ذلك مناسبًا: الوسائط، والمُرجَعات، والأخطاء، والأمثلة. على سبيل المثال، ينبغي أن تصف دالة مسح نظام الملفات مسار الدليل وراية التكرار التي تقبلها، والاكتشافات التي تُرجعها، وشروط الأخطاء (مثل مسار مفقود أو أذونات غير كافية)، ومثال استخدام موجز.

الاختبار

ضع اختبارات الوحدة بجانب الكود الذي تغطّيه، في وحدة اختبار داخل الملف نفسه. ينبغي أن يمارس كل اختبار سلوكًا واحدًا ويؤكّد نتيجة محدّدة -- على سبيل المثال، التحقق من أن مفتاح RSA بحجم 2048 بت يحصل على درجة المخاطر الكمومية المتوقّعة، أو أن تحليل شهادة غير صالحة يُرجع خطأً بدلًا من الانهيار.

الأداء

الأمان

مهم

شغّل تدقيق الأمان قبل كل إصدار للتأكد من عدم وجود ثغرات معروفة في التبعيات.

تدقيق الأمان

cargo audit

# Fix vulnerabilities
cargo audit fix

الكود غير الآمن

تحذير

تجنّب الكود unsafe ما لم يكن ضروريًا تمامًا. إذا لزم الأمر، وثّق سبب الحاجة إليه، وقدّم إثبات الأمان، وأضِف اختبارات مكثّفة، واطلب مراجعة من عدة مشرفين.

عندما يكون unsafe لا مفرّ منه، يجب أن يحمل كل كتلة من هذا النوع قسمًا توثيقيًا # Safety يشرح بالضبط سبب سلامة العملية.

معالجة الأخطاء

استخدم anyhow لأخطاء التطبيق وthiserror لأخطاء المكتبة. عرّف صيغ أخطاء صريحة ومُصنَّفة للمكتبة (على سبيل المثال، إخفاقات تحليل الشهادات، وأخطاء الإدخال/الإخراج، وأخطاء الخوارزمية غير الصالحة)، وأرفِق سياقًا وصفيًا بكل عملية قابلة للفشل بحيث يسهل تتبّع الإخفاقات إلى مصدرها.

التسجيل

استخدم tracing للتسجيل المُهيكَل. أصدِر رسالة على مستوى info عند بدء عملية رئيسية (مثل بدء مسح دليل)، وتحذيرًا عند حدوث مشكلة قابلة للتعافي (مثل مدخل دليل يتعذّر الوصول إليه)، ورسائل على مستوى debug لتفاصيل التقدّم الأدق.

اتفاقية رسائل التأكيد

اتبع Conventional Commits:

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

<body>

<footer>

النوع	الوصف
feat	ميزة جديدة
fix	إصلاح خطأ
docs	تغييرات في التوثيق
style	تغييرات في أسلوب الكود (التنسيق)
refactor	إعادة هيكلة الكود
perf	تحسينات الأداء
test	إضافة اختبارات
chore	مهام الصيانة

عملية طلب السحب

1

إنشاء طلب السحب

أنشئ طلب سحب بعنوان ووصف واضحين.

2

ربط المشكلات ذات الصلة

استخدم "Closes #123" لربط المشكلات ذات الصلة.

3

ضمان اجتياز الاختبارات

يجب أن تكون جميع فحوص CI خضراء.

4

طلب المراجعة

أشِر إلى المشرفين المعنيين لمراجعة الكود.

5

معالجة الملاحظات

أجرِ التغييرات المطلوبة فورًا.

6

ضغط التأكيدات

قبل الدمج، إذا طلب المشرفون ذلك.

عملية الإصدار

1

تحديث الإصدار

حدّث إصدار المشروع في بيان الحزمة.

2

تحديث سجل التغييرات

حدّث CHANGELOG.md بملاحظات الإصدار.

3

إنشاء وسم الإصدار

git tag v1.0.0

4

دفع الوسم

git push --tags

5

بناء الإصدار

cargo build --release

6

النشر

cargo publish

المجتمع

GitHub قنوات التواصل

• GitHub Issues: تقارير الأخطاء وطلبات الميزات
• GitHub Discussions: الأسئلة والمناقشات العامة
• Discord: الدردشة الفورية (الرابط في README)

Code مدوّنة السلوك

نتبع مدوّنة سلوك Rust. كن محترمًا وشاملًا وبنّاءً في جميع التفاعلات.

الترخيص

بالمساهمة، فإنك توافق على أن مساهماتك ستُرخَّص بموجب الترخيص نفسه للمشروع (انظر ملف LICENSE).

أسئلة؟

إذا كانت لديك أسئلة:

1. راجع التوثيق الموجود
2. ابحث في مشكلات GitHub
3. اسأل في GitHub Discussions
4. تواصل مع المشرفين

نصيحة

شكرًا لمساهمتك في ماسح PQC! كل مساهمة، مهما كانت صغيرة، تساعد في تحسين المشروع.