مستندات

• راهنمای محتوا
• دستورالعمل‌های RST و cheat sheet

این راهنمای مقدماتی به شما کمک می‌کند ابزارها و دانش لازم برای مشارکت در مستندات را به دست آورید.

اگر با زبان reStructuredText آشنا نیستید، مقدمه آن را بخوانید. سپس، دو روش برای شروع مشارکت در مستندات وجود دارد:

• برای تغییرات جزئی، مانند افزودن یک پاراگراف یا اصلاح یک typo، توصیه می‌کنیم از رابط GitHub استفاده کنید. این آسان‌ترین و سریع‌ترین راه برای ارسال تغییرات است، و برای افراد غیر فنی مناسب است. مستقیماً به بخش مشارکت در مستندات بروید تا شروع کنید.

• برای تغییرات پیچیده‌تر، مانند افزودن یک صفحه جدید، استفاده از Git و کار از یک کپی محلی از مستندات ضروری است. ابتدا دستورالعمل‌های بخش راه‌اندازی محیط را برای آماده‌سازی محیط خود دنبال کنید.

همچنین ببینید

راه‌های دیگر مشارکت در Odoo را کشف کنید

reStructuredText (RST) — متن بازساختارمند

مستندات به reStructuredText (RST) نوشته شده است، یک lightweight markup language که شامل متن معمولی همراه با markup است، که اجازه می‌دهد headings، images، notes و غیره گنجانده شوند. RST آسان برای استفاده است، حتی اگر با آن آشنا نباشید.

مهم

هنگام نوشتن مستندات از دستورالعمل‌های content و RST ما آگاه باشید. این تضمین می‌کند که مستندات سازگار می‌ماند و تأیید تغییرات توسط تیم Odoo را تسهیل می‌کند.

راه‌اندازی محیط

دستورالعمل‌های زیر به شما کمک می‌کند محیط خود را برای ایجاد تغییرات محلی در مستندات و سپس push کردن آن‌ها به GitHub آماده کنید. اگر قبلاً این مرحله را تکمیل کرده‌اید یا می‌خواهید از رابط GitHub تغییراتی ایجاد کنید، از این بخش رد شوید و به مشارکت در مستندات بروید.

1. ابتدا، یک حساب GitHub ایجاد کنید. Odoo از GitHub برای مدیریت کد منبع محصولات خود استفاده می‌کند، و این جایی است که تغییرات خود را ارسال خواهید کرد.

2. یک کلید SSH جدید تولید کرده و آن را در حساب GitHub خود ثبت کنید.

3. به github.com/odoo/documentation بروید و روی دکمه Fork در گوشه بالا-راست کلیک کنید تا یک fork (your own copy) از مخزن در حساب خود ایجاد کنید. این یک کپی از پایگاه کد ایجاد می‌کند که می‌توانید بدون تأثیر بر پایگاه کد اصلی در آن تغییراتی ایجاد کنید. اگر در Odoo کار می‌کنید این مرحله را رد کنید.

4. Git را نصب کنید. این یک ابزار command-line (a text interface) است که اجازه می‌دهد تاریخچه تغییرات اعمال‌شده روی یک فایل را ردیابی کنید و مهم‌تر از آن، روی نسخه‌های مختلف آن فایل به‌طور هم‌زمان کار کنید. این بدان معنی است که نیازی به نگرانی درباره بازنویسی کار در حال انتظار شخص دیگری هنگام ایجاد تغییرات نیست.

   بررسی کنید که مسیر نصب Git در متغیر PATH سیستم شما گنجانده شده باشد.

   Linux and macOSWindows

   از راهنمای به‌روزرسانی متغیر PATH در Linux و macOS با مسیر نصب Git (به طور پیش‌فرض /usr/bin/git) پیروی کنید.

5. Git را پیکربندی کنید تا خود را به‌عنوان نویسنده مشارکت‌های آینده‌تان شناسایی کنید. همان آدرس ایمیلی را که برای ثبت‌نام در GitHub استفاده کردید وارد کنید.

   $ git config --global user.name "Your Name"
   $ git config --global user.email "youremail@example.com"
   

6. منابع را با Git کلون کنید و به مخزن محلی بروید.

   $ git clone git@github.com:odoo/documentation.git
   $ cd documentation
   

7. Git را پیکربندی کنید تا تغییرات را به fork خود push کند به‌جای codebase اصلی. در دستورات زیر، <your_github_account> را با نام حساب GitHub که fork را روی آن ایجاد کرده‌اید جایگزین کنید. اگر در Odoo کار می‌کنید این مرحله را رد کنید.

   $ git remote add dev git@github.com:<your_github_account>/documentation.git
   

8. Git را پیکربندی کنید تا همکاری بین writers که از سیستم‌های مختلف می‌آیند را آسان کند.

   Linux and macOSWindows

   $ git config --global core.autocrlf input
   $ git config commit.template `pwd`/commit_template.txt
   

9. آخرین نسخه Python و pip را نصب کنید.

10. وابستگی‌های Python مستندات را با pip نصب کنید.

    $ pip install -r requirements.txt
    

    تأیید کنید که دایرکتوری نصب وابستگی‌های Python در متغیر PATH سیستم شما گنجانده شده است.

    Linux and macOSWindows

    راهنمای به‌روزرسانی متغیر PATH در Linux و macOS را با مسیر نصب وابستگی‌های Python دنبال کنید (به‌طور پیش‌فرض ~/.local/bin).

11. Make را نصب کنید.

    LinuxmacOSWindows

    $ sudo apt install make -y
    

12. pngquant را نصب کنید.

13. شما اکنون آماده اولین مشارکت خود با Git هستید.

مشارکت در مستندات

Contribute from the GitHub interfaceContribute with Git

1. ابتدا، یک حساب GitHub ایجاد کنید. Odoo از GitHub برای مدیریت کد منبع محصولات خود استفاده می‌کند، و این جایی است که تغییرات خود را ارسال خواهید کرد.

2. تأیید کنید که مستندات را در نسخه‌ای که قصد تغییر آن را دارید مرور می‌کنید. نسخه را می‌توان از منوی کشویی در منوی بالا انتخاب کرد.

3. به صفحه‌ای که می‌خواهید تغییر دهید بروید و روی دکمه Edit on GitHub در گوشه بالا-راست صفحه کلیک کنید.

4. روی دکمه Fork this repository کلیک کنید تا یک fork (your own copy) از مخزن در حساب خود ایجاد کنید. این یک کپی از پایگاه کد ایجاد می‌کند که می‌توانید بدون تأثیر بر پایگاه کد اصلی در آن تغییراتی ایجاد کنید. اگر در Odoo کار می‌کنید این مرحله را رد کنید.

   

5. تغییرات مورد نظر را اعمال کنید در حالی که از دستورالعمل‌های content و RST پیروی می‌کنید.

   نکته

   روی دکمه Preview changes کلیک کنید تا مشارکت خود را در فرمت قابل خواندن‌تر برای انسان مرور کنید. آگاه باشید که preview نمی‌تواند همه markups را به‌درستی مدیریت کند. به‌عنوان مثال، notes و tips به‌صورت متن ساده نمایش داده می‌شوند.

6. به پایین صفحه بروید و فرم کوچک را برای پیشنهاد تغییرات خود پر کنید. در اولین کادر متنی، خلاصه‌ای بسیار کوتاه از تغییرات خود بنویسید. به‌عنوان مثال، "Fix a typo" یا "Add documentation for invoicing of sales orders." در دومین کادر متنی، توضیح دهید چرا این تغییرات را پیشنهاد می‌کنید. سپس، روی دکمه Propose changes کلیک کنید.

   

7. تغییرات خود را بازبینی کرده و روی دکمه Create pull request کلیک کنید.

8. چک‌باکس Allow edits from maintainer را علامت بزنید. اگر در Odoo کار می‌کنید، این مرحله را رد کنید.

9. خلاصه‌ای را که در مورد تغییرات خود نوشتید مرور کنید و دوباره روی دکمه Create pull request کلیک کنید.

10. در پایین صفحه، وضعیت قابلیت ادغام را بررسی کرده و هر مشکلی را برطرف کنید.

11. به‌محض اینکه PR شما آماده ادغام است، یکی از اعضای تیم Odoo به‌طور خودکار برای بازبینی اختصاص داده می‌شود. اگر بازبین سؤالات یا اظهارنظرهایی داشته باشد، آن‌ها را به‌عنوان نظرات ارسال می‌کند و شما از طریق ایمیل مطلع می‌شوید. آن نظرات باید برای پیشرفت مشارکت حل شوند.

12. وقتی تغییرات شما تأیید شد، بازبین آن‌ها را ادغام می‌کند و روز بعد به‌صورت آنلاین ظاهر می‌شوند.