المساهمة

شكراً لك على التفكير في المساهمة في FORGE. سواء كنت تبلغ عن خطأ، أو تقترح ميزة، أو تحسن التوثيق، أو تقدم كوداً، يرشدك هذا الدليل خلال العملية من الإعداد إلى طلب السحب.

البدء

المتطلبات الأساسية

قبل المساهمة، تأكد من تثبيت ما يلي:

الأداة	الإصدار	الغرض
Rust	1.75+	تجميع FORGE CLI والنواة
Cargo	(مرفق مع Rust)	نظام البناء ومدير الحزم
Git	2.30+	التحكم في الإصدارات
Node.js	18+	بناء ومعاينة التوثيق
Docker	24+	تشغيل اختبارات التكامل
PostgreSQL	15+	قاعدة بيانات لاختبارات التكامل

الاستنساخ والبناء

# Clone the repository
git clone https://github.com/forge/forge.git
cd forge

# Build the project
cargo build

# Run the test suite
cargo test

# Run with debug output
RUST_LOG=debug cargo run -- new --name=testapp

TIP

البناء الأول يحمّل ويجمّع جميع التبعيات، مما قد يستغرق بضع دقائق. البناءات اللاحقة تكون تدريجية وأسرع بكثير.

التحقق من الإعداد

شغّل ما يلي للتأكد من أن كل شيء يعمل:

# Build in release mode
cargo build --release

# Run clippy for code linting
cargo clippy -- -D warnings

# Check formatting
cargo fmt --check

هيكل المشروع

FORGE منظم كـ Cargo workspace مع صندوقين:

forge/
├── Cargo.toml              # Workspace root
├── forge-cli/               # CLI binary crate
│   ├── src/
│   │   ├── main.rs          # Entry point and command routing
│   │   ├── commands/        # CLI command implementations
│   │   └── utils/           # CLI utilities (output, prompts)
│   └── Cargo.toml
│
├── forge-core/              # Library crate (business logic)
│   ├── src/
│   │   ├── lib.rs           # Library root
│   │   ├── config/          # Project configuration parsing
│   │   ├── generator/       # Code generation engine
│   │   ├── template/        # Template loading and rendering
│   │   ├── providers/       # Provider contract definitions
│   │   └── validators/      # Input and configuration validation
│   └── Cargo.toml
│
├── templates/               # Tera template files
│   ├── backends/
│   │   └── rust/            # Rust + Axum backend templates
│   ├── frontends/
│   │   └── nextjs/          # Next.js frontend templates
│   └── infra/               # Docker, Caddy, config templates
│
├── docs/                    # VitePress documentation (this site)
├── tests/                   # Integration tests
└── README.md

الصناديق الرئيسية

الصندوق	النوع	الوصف
forge-cli	ثنائي	يحلل وسائط CLI، يوزع الأوامر، يدير إخراج الطرفية
forge-core	مكتبة	تحليل التكوين، تقديم القوالب، توليد الملفات، التحقق

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

1. إنشاء فرع

اعمل دائماً على فرع ميزة، وليس مباشرة على main:

# Create branch from main
git checkout main
git pull origin main
git checkout -b feat/my-feature

استخدم بادئات أسماء الفروع هذه:

البادئة	الغرض	مثال
feat/	ميزة جديدة	feat/add-nuxtjs-support
fix/	إصلاح خطأ	fix/template-rendering-error
docs/	توثيق فقط	docs/update-api-contracts
refactor/	إعادة هيكلة الكود	refactor/simplify-generator
test/	إضافات اختبارات	test/add-config-validation

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

اكتب الكود وفقاً لإرشادات الأسلوب أدناه. اجعل الالتزامات مركزة -- كل التزام يجب أن يمثل تغييراً منطقياً واحداً.

3. اختبار التغييرات

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run clippy
cargo clippy -- -D warnings

# Check formatting
cargo fmt --check

4. تقديم طلب سحب

# Push the branch
git push -u origin feat/my-feature

ثم افتح طلب سحب على GitHub. تضمّن:

• عنوان واضح يصف ما يفعله الـ PR
• وصف للتغييرات ولماذا هي مطلوبة
• خطوات لاختبار التغييرات يدوياً (إن أمكن)
• لقطات شاشة لتغييرات واجهة المستخدم

WARNING

يجب أن تجتاز جميع طلبات السحب فحوصات CI قبل الدمج. يشمل ذلك الاختبارات وclippy والتنسيق.

تطوير القوالب

القوالب هي قلب FORGE. كل ملف في مشروع مولّد يُقدم من قالب Tera.

هيكل ملفات القوالب

ملفات القوالب تستخدم امتداد .tera وتوجد تحت templates/:

templates/backends/rust/api/src/handlers/auth.rs.tera

هذا القالب يولّد الملف:

{output}/apps/api/src/handlers/auth.rs

متغيرات القالب

القوالب لديها وصول إلى تكوين المشروع عبر متغيرات السياق:

{{ project_name }}          - اسم التطبيق
{{ project_name_pascal }}   - الاسم بـ PascalCase
{{ auth_method }}           - "email"، "mobile"، أو "otp"
{{ default_language }}      - كود اللغة الافتراضية
{{ languages }}             - مصفوفة كائنات اللغة
{{ features }}              - الميزات المفعّلة

التوليد الشرطي

استخدم شروط Tera لتضمين أو استبعاد الكود بناءً على التكوين:

// In .tera template file
{% if auth_method == "otp" %}
pub async fn send_otp(/* ... */) -> Result<Json<Value>, AppError> {
    // OTP-specific logic
}
{% endif %}

اختبار القوالب

اختبر أن قوالبك تُقدم بشكل صحيح عن طريق توليد مشروع وفحص المخرجات:

# Build FORGE
cargo build

# Generate test project
./target/debug/forge new --name=test-output

# Inspect generated files
cat test-output/apps/api/src/handlers/auth.rs

TIP

عند تعديل القوالب، اختبر دائماً مع مجموعات تكوين متعددة (طرق مصادقة مختلفة، لغات مختلفة، ميزات مفعّلة/معطّلة) لضمان تقديم جميع مسارات الكود بشكل صحيح.

إرشادات أسلوب القوالب

• حافظ على اتفاقيات لغة الملف المخرج (مثل أساليب Rust لملفات .rs.tera)
• استخدم كتل {% raw %}...{% endraw %} حول المحتوى الذي يحتوي على صياغة شبيهة بـ Tera (مثل الأقواس المعقوفة في JSX)
• اجعل منطق القالب في حده الأدنى -- فضّل توليد كود نظيف وقابل للقراءة على حيل القوالب الذكية
• أضف تعليقات في المخرجات المولدة تشرح الأنماط غير الواضحة

أسلوب الكود

كود Rust

FORGE يتبع اتفاقيات Rust القياسية المفروضة بواسطة rustfmt و clippy:

# Format all code
cargo fmt

# Run linter with warnings as errors
cargo clippy -- -D warnings

الاتفاقيات الرئيسية:

• استخدم snake_case للدوال والمتغيرات وأسماء الوحدات
• استخدم PascalCase للأنواع والصفات والـ enums
• فضّل Result<T, E> على الـ panics
• استخدم thiserror لأنواع الأخطاء
• وثّق واجهات API العامة بتعليقات ///
• اجعل الدوال أقل من 50 سطراً عند الإمكان

رسائل الالتزام

اتبع مواصفة Conventional Commits:

feat: add Nuxt.js frontend generator
fix: resolve template rendering for RTL languages
docs: update API contracts reference
refactor: simplify config parsing logic
test: add unit tests for permission validation
chore: update dependencies

قواعد رسالة الالتزام:

• استخدم الأمر المباشر (add، وليس added أو adds)
• اجعل سطر الموضوع أقل من 72 حرفاً
• أضف جسماً للتغييرات المعقدة يشرح "لماذا"
• ارجع لأرقام المشاكل عند الاقتضاء: fix: handle empty slug (#42)

الاختبار

FORGE يستخدم ثلاثة مستويات من الاختبار:

اختبارات الوحدة

اختبر الدوال والوحدات الفردية بمعزل.

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_validate_project_name() {
        assert!(validate_name("my-app").is_ok());
        assert!(validate_name("My App").is_err());
        assert!(validate_name("123app").is_err());
    }
}

اختبارات التكامل

اختبر خط أنابيب التوليد الكامل من التكوين إلى ملفات المخرجات.

// tests/integration/generate_test.rs

#[test]
fn test_generate_rust_backend() {
    let config = ProjectConfig {
        name: "test-app".into(),
        backend: Backend::Rust,
        auth_method: AuthMethod::Email,
        ..Default::default()
    };

    let output = tempdir().unwrap();
    generate_project(&config, output.path()).unwrap();

    // Verify expected files exist
    assert!(output.path().join("apps/api/src/main.rs").exists());
    assert!(output.path().join("apps/api/Cargo.toml").exists());
}

اختبارات تقديم القوالب

تحقق من أن القوالب تنتج مخرجات صالحة لجميع مجموعات التكوين.

#[test]
fn test_auth_handler_email_method() {
    let context = create_context(AuthMethod::Email);
    let output = render_template("backends/rust/api/src/handlers/auth.rs.tera", &context);

    assert!(output.contains("pub async fn login"));
    assert!(!output.contains("pub async fn send_otp"));
}

#[test]
fn test_auth_handler_otp_method() {
    let context = create_context(AuthMethod::Otp);
    let output = render_template("backends/rust/api/src/handlers/auth.rs.tera", &context);

    assert!(output.contains("pub async fn login"));
    assert!(output.contains("pub async fn send_otp"));
}

مساهمات التوثيق

موقع التوثيق مبني بـ VitePress ويوجد في دليل docs/.

تشغيل التوثيق محلياً

cd docs

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

كتابة التوثيق

• استخدم ميزات VitePress: تنبيهات ::: tip، ::: warning، ::: danger
• استخدم مجموعات الكود (::: code-group) لأمثلة متعددة اللغات أو الصيغ
• أضف جداول للبيانات المهيكلة بدلاً من النص الطويل
• ضمّن أمثلة كود عاملة كلما أمكن
• اربط بالصفحات ذات الصلة باستخدام مسارات نسبية: [المصادقة](/ar/backend/authentication)

تسمية الملفات

• استخدم الأحرف الصغيرة مع الشرطات: api-contracts.md، وليس ApiContracts.md
• ضع الملفات في الدليل المناسب المطابق لهيكل الشريط الجانبي
• حدّث .vitepress/config.mts إذا أضفت صفحة جديدة للشريط الجانبي

الإبلاغ عن المشاكل

تقارير الأخطاء

عند تقديم تقرير خطأ، تضمّن:

1. إصدار FORGE (forge --version)
2. نظام التشغيل والإصدار
3. إصدار Rust (rustc --version)
4. خطوات إعادة الإنتاج للمشكلة
5. السلوك المتوقع مقابل السلوك الفعلي
6. إخراج الخطأ (إخراج طرفية كامل، وليس لقطات شاشة)
7. التكوين (محتويات forge.yaml، إذا كان ذا صلة)

TIP

استخدم قالب مشكلة GitHub عند التوفر. يرشدك لتوفير جميع المعلومات الضرورية.

طلبات الميزات

طلبات الميزات يجب أن تتضمن:

1. بيان المشكلة -- ما الذي تحاول تحقيقه؟
2. الحل المقترح -- كيف يجب أن يتعامل معه FORGE؟
3. البدائل المدروسة -- مناهج أخرى فكرت فيها
4. السياق -- من سيستفيد من هذه الميزة؟

قواعد السلوك

يُتوقع من جميع المساهمين اتباع قواعد السلوك للمشروع:

• كن محترماً -- عامل الجميع باحترام. اختلف بشكل بنّاء.
• كن بنّاءً -- ركز على ما هو الأفضل للمشروع والمجتمع.
• كن تعاونياً -- شارك المعرفة وساعد الآخرين.
• كن صبوراً -- ليس لدى الجميع نفس مستوى الخبرة.
• لا للتحرش -- لن يُتسامح مع التحرش من أي نوع.

يجب الإبلاغ عن الانتهاكات لمشرفي المشروع عبر البريد الإلكتروني. جميع التقارير تبقى سرية.

الحصول على المساعدة

إذا احتجت مساعدة في مساهمتك:

• افتح نقاشاً للأسئلة
• تحقق من المشاكل الموجودة للمشاكل المعروفة
• اقرأ عقود الهندسة لمواصفات API
• راجع مخطط قاعدة البيانات لمرجع نموذج البيانات

انظر أيضاً

• المقدمة -- نظرة عامة على المشروع وفلسفته
• نظام القوالب -- كيف تعمل قوالب Tera
• توليد الكود -- خط أنابيب التوليد
• خارطة الطريق -- الميزات المخططة والأولويات