مستندات

• راهنمای محتوا
• RST guidelines and cheat sheet

This introductory guide will help you acquire the tools and knowledge needed to contribute to the documentation.

Read the introduction to the reStructuredText language if you are not familiar with it. Then, there are two courses of action to start contributing to the documentation:

• For minor changes, such as adding a paragraph or fixing a typo, we recommend using the GitHub interface. This is the easiest and fastest way to submit changes, and it is suitable for non-technical people. Jump directly to the Contributing to the documentation section to get started.

• For more complex changes, such as adding a new page, it is necessary to use Git and work from a local copy of the documentation. Follow the instructions in the راه‌اندازی محیط section first to prepare your environment.

همچنین ملاحظه نمائید

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

reStructuredText (RST)

The documentation is written in reStructuredText (RST), a lightweight markup language consisting of regular text augmented with markup, which allows including headings, images, notes, and so on. RST is easy to use, even if you are not familiar with it.

مهم

Be mindful of our content and RST guidelines as you write documentation. This ensures that the documentation stays consistent and facilitates the approval of changes by the Odoo team.

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

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

1. First, create a GitHub account. Odoo uses GitHub to manage the source code of its products, and this is where you will submit your changes.

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

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

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

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

   Linux and macOSWindows

   دستورالعمل‌های به‌روزرسانی متغیر PATH در لینوکس و 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 را طوری تنظیم کنید که تغییرات را به فورک خود ارسال کنید و نه به پایگاه کد اصلی. در دستورات زیر، <your_github_account> را با نام حساب GitHub که فورک را در آن ایجاد کرده‌اید جایگزین کنید. اگر در Odoo کار می‌کنید، این مرحله را نادیده بگیرید.

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

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

   Linux and macOSWindows

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

9. Install the latest release of Python and pip.

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

    $ pip install -r requirements.txt
    

    اطمینان حاصل کنید که دایرکتوری نصب وابستگی‌های Python در متغیر PATH سیستم شما قرار دارد.

    Linux and macOSWindows

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

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

    Linux and macOSWindows

    $ sudo apt install make -y
    

12. pngquant <https://pngquant.org/> را نصب کنید.

13. You are now ready to make your first contribution with Git.

Contributing to the documentation

Contribute from the GitHub interfaceContribute with Git

1. First, create a GitHub account. Odoo uses GitHub to manage the source code of its products, and this is where you will submit your changes.

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

3. به صفحه‌ای که قصد تغییر آن را دارید بروید و روی دکمه ویرایش در GitHub در گوشه بالا سمت راست صفحه کلیک کنید.

4. روی دکمه Fork این مخزن کلیک کنید تا یک فورک (نسخه خودتان) از مخزن در حساب خود ایجاد کنید. این کار یک کپی از پایگاه کد ایجاد می‌کند که می‌توانید تغییرات خود را بدون تأثیر بر پایگاه کد اصلی اعمال کنید. اگر در Odoo کار می‌کنید، این مرحله را نادیده بگیرید.

   

5. تغییرات مورد نظر خود را با رعایت راهنمایی‌های محتوا و RST اعمال کنید.

   نکته

   روی دکمه پیش‌نمایش تغییرات کلیک کنید تا مشارکت خود را در قالبی که برای انسان قابل‌خواندن‌تر است مرور کنید. به این نکته توجه داشته باشید که پیش‌نمایش قادر به نمایش صحیح تمام نشانه‌گذاری‌ها نیست. به عنوان مثال، یادداشت‌ها و نکات به صورت متن ساده نمایش داده می‌شوند.

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

   

7. تغییرات خود را مرور کرده و روی دکمه ایجاد درخواست pull کلیک کنید.

8. گزینه اجازه ویرایش توسط نگهدارنده را تیک بزنید. اگر در اودو کار می‌کنید، این مرحله را رد کنید.

9. خلاصه‌ای را که درباره تغییرات خود نوشته‌اید مرور کنید و دوباره روی دکمه ایجاد درخواست پول کلیک کنید.

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

11. As soon as your PR is ready for merging, a member of the Odoo team is automatically assigned for review. If the reviewer has questions or remarks, they will post them as comments and you will be notified by email. Those comments must be resolved for the contribution to go forward.

12. Once your changes are approved, the reviewer merges them and they appear online the next day.