قوالب Issues و Pull requests

قوالب الـ issues والـ pull requests نصوص جاهزة تضعها في الـ default branch للـ repository على ليڤانت غيت (LevantGit)، فتظهر تلقائيًا في نموذج فتح issue أو pull request. تحتاجها لتوجيه من يبلّغ عن خطأ إلى المعلومات التي تنقصك. اكتبها ملف Markdown بسيطًا، أو ملف YAML يبني نموذجًا بحقول وقوائم منسدلة ومربعات اختيار.

بعض المشاريع لها أسئلة ثابتة يجب أن يجيب عنها من يفتح issue: «ما الذي حدث؟ ما الذي توقّعته؟ أيّ إصدار؟». بدل تكرار هذه الأسئلة في كل مرة، ضع قالبًا في الـ default branch للـ repository، فيظهر محتواه في النموذج تلقائيًا ويوفّر جولات الاستيضاح الأولى.

ملاحظة

القوالب خاصة بكل repository؛ لا توجد قوالب عامة على مستوى الحساب. إن أردت القالب نفسه في repositories كثيرة، ضعه في template repository.

يمكنك أيضًا تمرير عنوان ونص جاهزين في رابط صفحة الـ issue الجديدة: ?title=Issue+Title&body=Issue+Text. عندها يُستخدم ما في الرابط بدل القالب.

أسماء الملفات

ضع الملف في جذر الـ repository أو في مجلد .gitea/ أو .github/. الأسماء المقبولة لقالب الـ issue:

• ISSUE_TEMPLATE.md
• ISSUE_TEMPLATE.yaml
• ISSUE_TEMPLATE.yml
• issue_template.md
• issue_template.yaml
• issue_template.yml
• .gitea/ISSUE_TEMPLATE.md
• .gitea/ISSUE_TEMPLATE.yaml
• .gitea/ISSUE_TEMPLATE.yml
• .gitea/issue_template.md
• .gitea/issue_template.yaml
• .gitea/issue_template.yml
• .github/ISSUE_TEMPLATE.md
• .github/ISSUE_TEMPLATE.yaml
• .github/ISSUE_TEMPLATE.yml
• .github/issue_template.md
• .github/issue_template.yaml
• .github/issue_template.yml

الأسماء المقبولة لملف إعداد الـ issues (انظر «ملف الإعداد» أدناه):

• .gitea/ISSUE_TEMPLATE/config.yaml
• .gitea/ISSUE_TEMPLATE/config.yml
• .gitea/issue_template/config.yaml
• .gitea/issue_template/config.yml
• .github/ISSUE_TEMPLATE/config.yaml
• .github/ISSUE_TEMPLATE/config.yml
• .github/issue_template/config.yaml
• .github/issue_template/config.yml

الأسماء المقبولة لقالب الـ pull request:

• PULL_REQUEST_TEMPLATE.md
• PULL_REQUEST_TEMPLATE.yaml
• PULL_REQUEST_TEMPLATE.yml
• pull_request_template.md
• pull_request_template.yaml
• pull_request_template.yml
• .gitea/PULL_REQUEST_TEMPLATE.md
• .gitea/PULL_REQUEST_TEMPLATE.yaml
• .gitea/PULL_REQUEST_TEMPLATE.yml
• .gitea/pull_request_template.md
• .gitea/pull_request_template.yaml
• .gitea/pull_request_template.yml
• .github/PULL_REQUEST_TEMPLATE.md
• .github/PULL_REQUEST_TEMPLATE.yaml
• .github/PULL_REQUEST_TEMPLATE.yml
• .github/pull_request_template.md
• .github/pull_request_template.yaml
• .github/pull_request_template.yml

نصيحة

قادم من GitHub؟ مجلد .github/ الذي لديك يعمل كما هو على ليڤانت غيت.

عدّة قوالب في مجلد

إن أردت أن يختار المستخدم بين قوالب («بلاغ خطأ»، «طلب ميزة»، «سؤال»)، ضع عدّة ملفات .md أو .yaml/.yml داخل مجلد بأحد هذه الأسماء:

• ISSUE_TEMPLATE
• issue_template
• .gitea/ISSUE_TEMPLATE
• .gitea/issue_template
• .github/ISSUE_TEMPLATE
• .github/issue_template
• .gitlab/ISSUE_TEMPLATE
• .gitlab/issue_template

عندها يعرض زر New Issue صفحة اختيار بين القوالب.

قالب Markdown

---

name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
assignees: ["user1"]
labels:

- bug
- "help needed"

---

This is the template!

في صفحة الاختيار يظهر هذا القالب باسم Template Name ووصفه This template is for testing!. وعند فتح issue به يُملأ العنوان مسبقًا بـ [TEST] والنص بـ This is the template!، ويصير user1 هو الـ assignee، ويُضاف الـ labels bug وhelp needed، وتشير الـ issue إلى الـ branch main.

قالب YAML (نموذج بحقول)

قالب YAML لا يضع نصًا جاهزًا فقط، بل يبني نموذجًا من حقول حقيقية: نص قصير، نص طويل، قائمة منسدلة، مربعات اختيار. هذا مثال كامل لبلاغ خطأ:

name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  # some markdown that will only be visible once the issue has been created
  - type: markdown
    attributes:
      value: |
        This issue was created by an issue **template** :)
    visible: [content]
  - type: input
    id: contact
    attributes:
      label: Contact Details
      description: How can we get in touch with you if we need more info?
      placeholder: ex. [email protected]
    validations:
      required: false
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Also tell us, what did you expect to happen?
      placeholder: Tell us what you see!
      value: "A bug happened!"
    validations:
      required: true
  - type: dropdown
    id: version
    attributes:
      label: Version
      description: What version of our software are you running?
      options:
        - 1.0.2 (Default)
        - 1.0.3 (Edge)
    validations:
      required: true
  - type: dropdown
    id: browsers
    attributes:
      label: What browsers are you seeing the problem on?
      multiple: true
      options:
        - Firefox
        - Chrome
        - Safari
        - Microsoft Edge
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
      render: shell
  - type: checkboxes
    id: terms
    attributes:
      label: Code of Conduct
      hide_label: true
      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
      options:
        - label: I agree to follow this project's Code of Conduct
          required: true
        - label: I have also read the CONTRIBUTION.MD
          required: true
          visible: [form]
        - label: This is a TODO only visible after issue creation
          visible: [content]

كل عنصر في body له type وattributes واختياريًا validations وvisible. مفتاح visible يحدّد أين يظهر العنصر: form في النموذج فقط، أو content في نص الـ issue بعد إنشائها فقط، أو كلاهما. فيما يلي أنواع العناصر ومفاتيحها.

markdown

نص Markdown يُعرض في النموذج لإرشاد المستخدم، ولا يُرسل مع الـ issue افتراضيًا.

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي
value	النص المعروض؛ يدعم تنسيق Markdown.	إلزامي	نص	-

visible: الافتراضي [form].

textarea

حقل نص متعدد الأسطر. يستطيع المستخدم إرفاق ملفات فيه.

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي	القيم المقبولة
label	وصف قصير للمطلوب، يظهر في النموذج.	إلزامي	نص	-	-
hide_label	إن كان true يُخفى العنوان المعتاد للحقل.	اختياري	منطقي	false	-
description	شرح إضافي يظهر في النموذج.	اختياري	نص	فارغ	-
placeholder	نص باهت يظهر حين يكون الحقل فارغًا.	اختياري	نص	فارغ	-
value	نص يُملأ مسبقًا في الحقل.	اختياري	نص	-	-
render	إن حُدّدت قيمة، يُنسَّق النص المُرسَل ككتلة كود بهذه اللغة. عندها لا يدعم الحقل إرفاق الملفات ولا محرّر Markdown.	اختياري	نص	-	اللغات التي يعرفها ليڤانت غيت

التحقق (validations):

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي
required	يمنع الإرسال حتى يُملأ الحقل.	اختياري	منطقي	false

visible: الافتراضي [form, content].

input

حقل نص من سطر واحد.

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي
label	وصف قصير للمطلوب، يظهر في النموذج.	إلزامي	نص	-
hide_label	إن كان true يُخفى العنوان المعتاد للحقل.	اختياري	منطقي	false
description	شرح إضافي يظهر في النموذج.	اختياري	نص	فارغ
placeholder	نص باهت يظهر حين يكون الحقل فارغًا.	اختياري	نص	فارغ
value	نص يُملأ مسبقًا في الحقل.	اختياري	نص	-

التحقق (validations):

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي	القيم المقبولة
required	يمنع الإرسال حتى يُملأ الحقل.	اختياري	منطقي	false	-
is_number	يمنع الإرسال حتى يحوي الحقل رقمًا.	اختياري	منطقي	false	-
regex	يمنع الإرسال حتى تطابق القيمة التعبير النمطي.	اختياري	نص	-	تعبير نمطي (regular expression)

visible: الافتراضي [form, content].

dropdown

قائمة منسدلة.

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي
label	وصف قصير للمطلوب، يظهر في النموذج.	إلزامي	نص	-
hide_label	إن كان true يُخفى العنوان المعتاد للحقل.	اختياري	منطقي	false
description	شرح إضافي يظهر في النموذج.	اختياري	نص	فارغ
multiple	هل يستطيع المستخدم اختيار أكثر من خيار؟	اختياري	منطقي	false
list	إن كان true تُعرض الخيارات المختارة كقائمة؛ وإلا في سطر واحد مفصولة بفواصل.	اختياري	منطقي	false
options	مصفوفة الخيارات. لا تكون فارغة، وكل الخيارات مختلفة.	إلزامي	مصفوفة نصوص	-

التحقق (validations):

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي
required	يمنع الإرسال حتى يُختار خيار.	اختياري	منطقي	false

visible: الافتراضي [form, content].

checkboxes

مجموعة مربعات اختيار.

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي
label	وصف قصير للمطلوب، يظهر في النموذج.	إلزامي	نص	-
hide_label	إن كان true يُخفى العنوان المعتاد للمجموعة.	اختياري	منطقي	false
description	شرح للمجموعة يظهر في النموذج؛ يدعم Markdown.	اختياري	نص	فارغ
options	مصفوفة المربعات؛ صيغتها أدناه.	إلزامي	مصفوفة	-

لكل عنصر في options:

المفتاح	الوصف	إلزامي؟	النوع	الافتراضي
label	نص المربع كما يظهر في النموذج؛ يدعم Markdown للخط العريض والمائل والروابط.	إلزامي	نص	-
required	يمنع الإرسال حتى يُعلَّم المربع.	اختياري	منطقي	false
visible	أين يظهر هذا المربع تحديدًا: form أو content أو كلاهما.	اختياري	مصفوفة نصوص	-

visible: الافتراضي [form, content].

ملف الإعداد

ملف config.yaml داخل مجلد القوالب يتحكّم بصفحة الاختيار:

blank_issues_enabled: true
contact_links:
  - name: LevantGit
    url: https://levantgit.com
    about: Visit the LevantGit Website

المفتاح	الوصف	النوع	الافتراضي
blank_issues_enabled	إن كان false يُجبر المستخدم على اختيار قالب ولا يستطيع فتح issue فارغة.	منطقي	true
contact_links	روابط إضافية تظهر في صفحة الاختيار (مثل رابط منتدى أو بريد دعم).	مصفوفة روابط	فارغة

لكل رابط في contact_links:

المفتاح	الوصف	النوع	إلزامي؟
name	اسم الرابط	نص	نعم
url	عنوان الرابط	نص	نعم
about	وصف قصير للرابط	نص	نعم

ماذا بعد؟

• Labels: الـ labels التي يضيفها القالب يجب أن تكون موجودة في الـ repository أولًا.
• Pull requests: كيف يُراجَع الـ pull request بعد فتحه بالقالب.
• Markdown: كل ما يمكنك كتابته في نص القالب.

---

هذه الصفحة مبنية على وثائق Gitea (رخصة MIT) بعد ترجمتها وتبسيطها.