چگونه در فلاسک مشارکت کنیم¶

از توجه کردن شما به کمک به فلاسک ممنونیم!

سوال های پشتیبانی¶

لطفا از ابزار ردیابی مشکل (issue tracker) برای این استفاده نکنید. ابرار ردیابی مشکل یک ابزار است که مکان باگ ها و درخواست قابلیت ها را در فلاسک نشان می دهد. از یکی از منابع آمده برای سوال های در مورد فلاسک یا مشکلات کد خود استفاده کنید:

کانال #questions در دیسکورد ما : https://discord.gg/pallets
در Stack Overflow سوال خود را بپرسید. در گوگل جستجو کنید: site:stackoverflow.com flask {search term, exception message, etc.}
برای بحث طولانی مدت یا سؤالات بزرگتر را در GitHub Discussions از ما بپرسید

گزارش مشکلات¶

موارد زیر را در پست خود جای دهید:

توضیح دهید چگونه این اتفاق برای شما افتاد.
اگر ممکن است، یک مثال مشابه قابل تکثیر بنویسید تا به ما کمک کنید. مشکل خود را شناسایی کنید. شناسایی مشکل هم کمک می کند تا بررسی کنید که مشکل از سمت کد شما نیست.
توضیح دهید چگونه این اتفاق برای شما افتاد. جزئیات کامل را شرح دهید اگر با خطایی مواجه شدید.
نسخه های پایتون و فلاسک خود را بنویسید. اگر ممکن است، چک کنید که آیا مشکل در آخرین نسخه رسمی یا آخرین نسخه مخزن حل شده است یا خیر.

اعمال پچ (patch) ها¶

اگر مشکلی برای آنچه می خواهید ارسال کنید وجود ندارد، یک مشکل جدید برای گفتگو قبل از کار بر روی پول ریکوئست (pull request) باز کنید. شما می توانید روی هر موضوعی کار کنید که یک پول ریکوئست باز مرتبط با آن یا یک مسئول اختصاص داده شده به آن ندارد. اینها در نوار کناری نشان داده می شوند. نیازی نیست بپرسید که آیا می توانید روی یک موضوع کار کنید که به آن علاقه مندید.

موارد زیر را در پچ خود وارد کنید:

از Black استفاده کنید تا کد خود را فرمت و مرتب کنید. این ابزار و دیگر ابزار ها می توانند به صورت خودکار اجرا شوند اگر شما pre-commit را نصب کنید.
اگر پچ شما کدی را اضافه یا تغییر می دهد، کد را تست کنید. مطمئن شوید که تست بدون پچ شما با خطا مواجه می شود.
هر گونه متن یا داک استرینگ (docstring) مرتبط را بروزرسانی کنید. هر سطر مستندات و داک استرینگ ها باید در 72 کاراکتر خلاصه شود.
یک ورودی در CHANGES.rst اضافه کنید. مانند دیگر ورودی ها از استایل مشابه استفاده کنید. همچنین .. versionchanged:: در خط تغییرات داخل خطی مرتبط با داک استرینگ را اضافه کنید.

First time setup using GitHub Codespaces¶

GitHub Codespaces creates a development environment that is already set up for the project. By default it opens in Visual Studio Code for the Web, but this can be changed in your GitHub profile settings to use Visual Studio Code or JetBrains PyCharm on your local computer.

مطمئن شوید که یک GitHub account دارید.
From the project's repository page, click the green "Code" button and then "Create codespace on main".
The codespace will be set up, then Visual Studio Code will open. However, you'll need to wait a bit longer for the Python extension to be installed. You'll know it's ready when the terminal at the bottom shows that the virtualenv was activated.
Check out a branch and start coding.

First time setup in your local environment¶

مطمئن شوید که یک GitHub account دارید.
آخرین نسخه گیت را دانلود کنید.

گیت خود را با username و email خود تنظیم کنید.

$ git config --global user.name 'your name'
$ git config --global user.email 'your email'

فلاسک را با فشردن دکمه Fork به اکانت گیت هاب خود فورک کنید.
Clone your fork locally, replacing your-username in the command below with your actual username.
```
$ git clone https://github.com/your-username/flask
$ cd flask
```

Create a virtualenv. Use the latest version of Python.

لینوکس / macOS

$ python3 -m venv .venv
$ . .venv/bin/activate

ویندوز

> py -3 -m venv .venv
> .venv\Scripts\activate

پیش نیاز های برنامه را نصب کنید، سپس فلاسک را در حالت قابل ویرایش نصب کنید.
```
$ python -m pip install -U pip
$ pip install -r requirements/dev.txt && pip install -e .
```
ابزار pre-commit را نصب کنید.
```
$ pre-commit install --install-hooks
```

شروع کد نویسی¶

شاخه ای برای شناسایی مشکلی که می خواهید روی آن کار کنید ایجاد کنید. اگر شما در حال ارائه رفع اشکال و یا رفع مشکلات اسناد هستید، شاخه کردن از آخرین شاخه ".x" است.
```
$ git fetch origin
$ git checkout -b your-branch-name origin/2.0.x
```
اگر شما در حال ارائه یک ویژگی و یا تغییر هستید، شاخه های دیگر از شاخه "main" منشا می گیرند.
```
$ git fetch origin
$ git checkout -b your-branch-name origin/main
```
با استفاده از ویرایشگر مورد علاقه خود، تغییرات خود را ایجاد کنید و کامیت کنید.
- If you are in a codespace, you will be prompted to create a fork the first time you make a commit. Enter Y to continue.
شامل تست هایی که هر گونه تغییرات کد شما را پوشش می دهد. مطمئن شوید که تست بدون پچ شما شکست می خورد و اجرا نمی شود. تست ها را همان طور که در زیر شرح داده شده اجرا کنید.
Push your commits to your fork on GitHub and create a pull request. Link to the issue being addressed with fixes #123 in the pull request description.
```
$ git push --set-upstream origin your-branch-name
```

اجرای تست ها¶

مجموعه تست های اولیه را با pytest اجرا کنید.

$ pytest

این کار تست ها را برای محیط فعلی اجرا می کند که معمولاً کافی است. CI مجموعه کامل را اجرا خواهد کرد زمانی که شما پول ریکوئست بزنید. شما می توانید مجموعه تست کامل با tox اجرا کنید اگر نمی خواهید که صبر کنید.

$ tox

اجرا کردن تست ها¶

تولید یک گزارش از خطوط که تست را پوشش نمی دهند می تواند نشان بدهد که از کجا باید برای مشارکت شروع کنید.'pytest'' را با استفاده از ''coverage'' اجرا کرده و یک گزارش تولید کنید.

If you are using GitHub Codespaces, coverage is already installed so you can skip the installation command.

$ pip install coverage
$ coverage run -m pytest
$ coverage html

''htmlcov/index.html'' را در مرورگر خود باز کنید تا گزارش را ببینید.

اطلاعات بیشتر در مورد 'coverage <https://coverage.readthedocs.io>'__.

ساخت اسناد¶

اسناد در دایرکتوری ''docs'' با استفاده از Sphinx بسازید.

$ cd docs
$ make html

''_build/html/index.html'' را در مرورگر خود باز کنید تا اسناد را مشاهده کنید.

اطلاعات بیشتر در مورد 'sphinx <https://www.sphinx-doc.org/en/stable/>'__.