Хичээл 1: Issues

Танилцуулга

Одоогоор таны төслийн ирээдүйн ажлууд хаана бүртгэгдэж байна вэ? Магадгүй толгойд тань, эсвэл цаасан тэмдэглэлд, эсвэл огт хаана ч биш. "Дундаж тооцоолох функцэд нэг алдаа байх шиг байсан", "ангиллаар нийлбэр гаргавал сайн байна" гэх мэт санаанууд төрж, хэдэн өдрийн дараа мартагддаг. Бүлэг 6 GitHub-ийн хамтын ажиллагааны хэрэгслүүдийн тухай бөгөөд тэдгээрийн эхнийх нь issue юм. Issue бол төсөлтэй холбоотой нэг ажил, нэг алдаа, эсвэл нэг санааг бүртгэдэг хуудас бөгөөд repository-ийн хажууд, кодтой нь холбогдон амьдардаг.

Багийн ажилд issue-үүд нь хэн юун дээр ажиллаж байгааг, юу хийгдэх ёстойг бүх хүнд харагдуулдаг гол хэрэгсэл юм. Мөн гаднын хүмүүс таны төслөөс алдаа олбол яг issue-ээр мэдээлдэг. Гэхдээ энэ хичээлд бид issue-г ганцаараа, өөрийн төсөл дээр ашиглана. Энэ нь эхэндээ хачин санагдаж болох ч ганцаараа ажилладаг хөгжүүлэгчид ч issue-г өөрийн ажлын жагсаалт болгон өргөн хэрэглэдэг. Энэ хичээлд бид зарлагын бүртгэлээс жинхэнэ алдаа олж, түүнийг issue болгон бүртгэнэ. Дараа нь алдааг засаж, commit message-ээр issue-г автоматаар хаана. Мөн тустай гарчиг бичих, label-ээр ангилах аргуудыг сурна.

Зүйрлэл: засварын газрын хүсэлтийн хуудас

Утас засварын газарт очоход ажилтан таны асуудлыг хуудсан дээр бичиж, түүнд дугаар өгдөг. “№ 147: дэлгэц хагарсан, мэдрэгч ажиллахгүй” гэх мэт. Тэр хуудас таны утастай хамт засварчин руу очдог. Засварчин юу хийснээ тэр хуудсан дээр тэмдэглэж, дууссан үед "хийгдсэн" гэж хаадаг. Хэрвээ та маргааш "миний утас ямар байдалтай байна вэ" гэж асуувал ажилтан дугаараар нь шууд олж хариулна. Хуудас бүр нэг асуудлын бүтэн түүх: юу болсон, юу хийсэн, хэзээ дууссан.

GitHub-ийн issue яг ийм хуудас. Issue бүр давтагдашгүй дугаартай: #1, #2, #3. Гарчиг, дэлгэрэнгүй тайлбар, ангиллын шошго, сэтгэгдлүүд, нээлттэй эсвэл хаалттай төлөвтэй. Хамгийн гол нь issue нь кодтой холбогддог: засварыг хийсэн commit issue-г дугаараар нь дурдаж, түүнийг хааж болно. Хэдэн сарын дараа "энэ алдааг хэзээ, яаж зассан бэ" гэсэн асуултын хариу issue-ийн хуудсанд бүтэн байна.

Анхны жишээ: жинхэнэ алдааг бүртгэх

Алхам 1: Алдааг олох

Гэрийн компьютерийн expense-tracker фолдероо VS Code-д нээж, дадлынхаа дагуу эхлээд pull хийнэ үү.

Command:

git pull

Гаралт:

Already up to date.

4.4 дүгээр хичээлд бид report.py-д дундаж тооцоолох функц нэмсэн. Түүнийг дахин харцгаая.

python

def average(expenses):
    return total(expenses) / len(expenses)

Энэ функцэд хоосон жагсаалт өгвөл юу болох вэ? len() тэг буцааж, Python тэгд хуваах гэж оролдоно. Үүнийг шалгаж үзье.

Command:

python -c "from report import average; print(average([]))"

Гаралт:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "C:\Users\Bat\expense-tracker\report.py", line 8, in average
    return total(expenses) / len(expenses)
           ~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~
ZeroDivisionError: division by zero

Traceback-ийг доороос нь дээш уншъя. Хамгийн доод мөр “ZeroDivisionError: division by zero” нь "тэгд хуваах алдаа" гэсэн утгатай. Дээш нь report.py-ийн 8 дугаар мөр, average функц дотор алдаа гарсан бөгөөд “~~~^~~~” тэмдгүүдийн “^” нь хуваах тэмдгийг яг онож заажээ. Хамгийн дээд хэсгийн “<string>“ нь бидний -c-ээр өгсөн кодыг заана. Ингээд бид жинхэнэ алдаа олов: хэрэглэгч ямар ч зарлагагүй үед программ унана.

Таны мөрийн дугаар report.py-ийн бүтцээс хамаараад өөр байж болно. Хамгийн гол нь ZeroDivisionError гарсан явдал.

Алхам 2: Шууд засахгүй, эхлээд бүртгэх

Ийм жижиг алдааг олоод шууд засах нь байгалийн хүсэл. Гэхдээ бодит ажил дээр алдаа ихэвчлэн ажлын дунд олддог: та өөр зүйл дээр ажиллаж байхдаа санамсаргүй анзаардаг. Тэр мөчид ажлаа орхиод алдаа засвал анхны ажил тань тасарна. Засахгүй орхивол алдаа мартагдана. Issue бол гуравдахь зам: алдааг одоо бүртгээд, хэзээ засахаа дараа шийдэх. Энэ хичээлд бид энэ дадлыг баримтлаад эхлээд issue үүсгэнэ.

Алхам 3: Issue үүсгэх

Browser дээр зарлагын бүртгэлийн repository хуудсаа нээж, дээд талын табуудаас “Issues” дээр дарна уу. Шинэ repository-д issue байхгүй тул хоосон хуудас харагдана. “New issue” товчийг дарна уу.

[Зураг: хоосон Issues таб ба “New issue” товч]

Нээгдсэн маягт хоёр үндсэн талбартай: Title буюу гарчиг, Description буюу тайлбар. Гарчгийн талбарт дараахыг бичнэ үү.

average() crashes on an empty expense list

Тайлбарын талбар Markdown дэмждэг тул 5.1 дүгээр хичээлд сурсан зүйлээ энд хэрэглэнэ. Дараах тайлбарыг бичнэ үү, traceback-ийг өөрийн terminal-аас хуулж тавиарай.

markdown

## What happens

Calling `average()` with an empty list raises `ZeroDivisionError`.

## Steps to reproduce

```powershell
python -c "from report import average; print(average([]))"
```

## Error

```
ZeroDivisionError: division by zero
```

## Expected

`average([])` should return `0` instead of crashing.

Тайлбарын талбарын дээд талд “Preview” таб байвал түүнийг дарж, Markdown хэрхэн харагдахыг шалгаарай. Дараа нь доод хэсгийн “Create” эсвэл “Submit new issue” товчийг дарна уу.

[Зураг: бөглөсөн issue маягт]

Issue үүслээ. Хуудасны дээд хэсэгт гарчиг болон “#1” дугаар, түүний хажууд ногоон “Open” буюу "нээлттэй" тэмдэг харагдана. Энэ бол таны repository-ийн анхны issue.

[Зураг: үүссэн issue #1-ийн хуудас]

Алхам 4: Label нэмэх

Issue хуудасны баруун талд хэд хэдэн тохиргоо бий: Assignees, Labels, Projects, Milestone. Labels буюу шошго нь issue-г төрлөөр нь ангилдаг. “Labels” дээр дарахад GitHub-ийн анхдагч шошгуудын жагсаалт гарна. Тэдгээрийн хамгийн их хэрэглэгддэг хоёр нь bug ба enhancement. Bug нь "алдаа", enhancement нь "сайжруулалт, шинэ боломж" гэсэн утгатай. Бусад анхдагч шошгууд ч бий: documentation нь баримт бичгийн ажил, question нь асуулт, good first issue нь шинэ хүнд тохиромжтой хялбар ажил гэх мэт. Энэ алдаанд “bug” сонгоно уу. Сонгосны дараа шошго өнгөт тэмдэг болж issue-ийн хажууд гарна.

[Зураг: Labels цэс, bug сонгосон]

Ганцаараа ажилладаг төсөлд label-ууд яагаад хэрэгтэй вэ? Issue олшрох тусам "одоо засах ёстой алдаанууд" болон "хэзээ нэгэн цагт хийх санаанууд" хоёрыг ялгах хэрэг гардаг. Issues табын жагсаалтыг шошгоор шүүж, жишээ нь зөвхөн bug-уудыг харж болно. Мөн reviewer таны repository-г үзэхэд шошготой, эмх цэгцтэй issue-үүд ажлаа зохион байгуулдаг хүн гэдгийг тань харуулна.

Тустай гарчиг ба тайлбар

Issue-ийн хамгийн чухал хэсэг бол гарчиг. Issues табын жагсаалтад зөвхөн гарчиг харагддаг тул гарчиг issue-г нээлгүйгээр ойлгуулах ёстой. Муу гарчгуудын жишээ: “bug”, "алдаа", “help”, “doesn’t work”, “average”. Эдгээр нь юу ч хэлэхгүй: ямар алдаа, хаана, ямар нөхцөлд? Сайн гарчиг тодорхой юм, асуудал эсвэл зорилгыг шууд нэрлэнэ: “average() crashes on an empty expense list”, “Show total per category”, “README run instructions miss the data file step”. Commit message-тэй адил энгийн англи хэллэг хангалттай.

Тайлбарын хувьд issue-ийн төрлөөс хамаарсан тогтсон бүтэц бий. Алдааны issue-д бидний дээр ашигласан гурван хэсэг хамгийн чухал: юу болж байна, түүнийг хэрхэн давтаж харах вэ, юу болох ёстой байсан бэ. Ялангуяа "хэрхэн давтах" хэсэг маш үнэ цэнтэй, учир нь давтаж харж чадахгүй алдааг засахад хэцүү. Алдааны мессежийг кодын блокт хуулж тавих нь "ямар нэг алдаа гарсан" гэж тайлбарлахаас хавьгүй илүү тустай. Шинэ боломжийн issue-д юу хүсэж байгаа, яагаад хэрэгтэй, магадгүй хэрхэн харагдах ёстойг бичнэ.

Энэ бүтэц ганцаараа ажиллахад ч тустай. Хоёр долоо хоногийн дараа issue-гээ нээхэд та алдааг хэрхэн олсноо мартсан байх магадлалтай, харин issue тань яг ямар command-аар давтаж харахыг хэлж өгнө.

Олон жишээ

Санааг issue болгох

Issue зөвхөн алдаанд биш, санаанд ч зориулагдсан. Дахин “New issue” дарж хоёр дахь issue үүсгэе.

Гарчиг:

Show total per category

Тайлбар:

markdown

Print a total for each category (for example food, transport)
in addition to the overall total.

This makes it easier to see where most of the money goes.

Үүсгэсний дараа label-ээс “enhancement” сонгоно уу. Энэ issue #2 дугаартай болно. Энэ санааг одоо хэрэгжүүлэхгүй, нээлттэй үлдээнэ. Бид түүн рүү Бүлэг 6-ийн удирдлагатай бүтээлд эргэж ирнэ. Нээлттэй issue-үүдийн жагсаалт бол таны төслийн хийх ажлын самбар: юу засах, юу нэмэх ёстой нь бүгд нэг газар харагдана.

Одоо Issues табыг нээвэл хоёр нээлттэй issue харагдана: #2 enhancement шошготой, #1 bug шошготой. Жагсаалтын дээд талын “Labels” шүүлтүүрээр зөвхөн нэг төрлийг харж болно.

[Зураг: хоёр нээлттэй issue бүхий Issues таб]

Алдааг засаж, commit-оор issue хаах

Одоо #1 алдааг засъя. VS Code-д report.py-г нээж, average функцийг дараах байдлаар өөрчилнө үү.

python

def average(expenses):
    if not expenses:
        return 0
    return total(expenses) / len(expenses)

“if not expenses” нь жагсаалт хоосон эсэхийг шалгана: Python-д хоосон жагсаалт худал утгатай гэдгийг өмнөх сургалтаас санаж байгаа. Хоосон бол тэг буцааж, хуваах мөрт хэзээ ч хүрэхгүй. Засвар ажиллаж байгааг Алхам 1-ийн command-аар шалгая.

Command:

python -c "from report import average; print(average([]))"

Гаралт:

0

Алдаа арилж, issue-д бичсэн “Expected” хэсэг биеллээ. Одоо commit хийнэ. Энэ удаад commit message-д онцгой зүйл нэмнэ.

Command:

git add report.py
git commit -m "Return 0 from average() for empty list (fixes #1)"
git push

Гаралт (сүүлийн мөрүүд):

[main 4b2d7e9] Return 0 from average() for empty list (fixes #1)
 1 file changed, 2 insertions(+)
...
To https://github.com/bat-dorj/expense-tracker.git
   3e6b8d1..4b2d7e9  main -> main

Commit message-ийн төгсгөлд “fixes #1” гэж бичсэнийг анзаараарай. GitHub commit message-ийг уншиж, “fixes”, “fix”, “closes”, “close”, “resolves” гэх мэт тусгай үгийн ард issue-ийн дугаар байвал тэр issue-г автоматаар хаадаг. Энэ нь commit repository-ийн үндсэн салаа, манай тохиолдолд main руу push хийгдсэн үед л ажиллана.

Browser дээр issue #1 хуудсаа дахин ачаална уу. Ногоон “Open” тэмдэг нил ягаан “Closed” болсон байна. Issue-ийн доод хэсэгт шинэ мөр гарч ирсэн: таны commit энэ issue-г хаасан гэсэн тэмдэглэл, commit-ын холбоостой. Тэр холбоос дээр дарвал 5.3 дугаар хичээлийн diff хуудас нээгдэж, яг ямар өөрчлөлт энэ алдааг зассаныг харуулна. Алдаа, түүний тайлбар, засвар бүгд нэг дор холбогдлоо.

[Зураг: хаагдсан issue #1, доод талд commit-ын холбоос]

Энэ холболт хоёр чиглэлтэй. GitHub-ийн commit-ын түүх рүү ороод тэр commit-ыг нээвэл message-ийн “#1” нь issue руу хөтлөх холбоос болсон байна. Хэдэн сарын дараа blame-ээр average функцийн “if not expenses” мөрийг харвал тэр commit, түүнээс issue руу, issue-ээс алдааны бүрэн тайлбар руу очно. 5.3 дугаар хичээлд blame-ийг "гарал үүслийг олох хэрэгсэл" гэж ярьсны жинхэнэ утга энэ.

Issue-г гараар хаах

Бүх issue код өөрчлөлтөөр хаагддаггүй. Заримдаа санаа хэрэггүй болдог, эсвэл алдаа нь алдаа биш байсан нь тодорхой болдог. Ийм үед issue хуудасны доод хэсгийн “Close issue” товчийг ашиглана. Товчны хажуудах сумыг дарвал хоёр сонголт гарч болно: “Close as completed” буюу "дууссан тул хаах", “Close as not planned” буюу "хийхгүй тул хаах". Хаахын өмнө сэтгэгдлийн талбарт шалтгаанаа нэг өгүүлбэрээр бичих нь сайн дадал, ирээдүйн өөртөө яагаад хаасныг хэлж өгнө. Хаасан issue-г хэзээ ч “Reopen issue” товчоор дахин нээж болно.

Туршаад үзээрэй

Хүсвэл зарлагын бүртгэлээ ажиллуулж үзэж, нэмж болох өөр санаа эсвэл өөр жижиг алдаа хайгаарай. Жишээ нь data файл байхгүй үед программ FileNotFoundError-оор унадаг нь 4.3 дугаар хичээлээс мэдэгдэж байгаа: тэр нь найрсаг мессеж гаргах ёстой юу? Олсон зүйлээ энэ хичээлийн бүтцээр issue болгож бүртгээрэй: тодорхой гарчиг, давтах алхам, хүлээгдэж буй үр дүн, тохирох шошго. Засах шаардлагагүй, бүртгэхэд л хангалттай.

Түгээмэл алдаанууд

Issue автоматаар хаагдахгүй байх. Хэрвээ commit message-д “fixes #1” бичсэн хэрнээ issue нээлттэй хэвээр байвал хэд хэдэн шалтгаан байж болно. Нэгдүгээрт, push хийгээгүй: git status “ahead” гэж хэлж байгаа эсэхийг шалгаарай. Хоёрдугаарт, commit main-ээс өөр салаанд байна: GitHub зөвхөн үндсэн салаанд орсон commit-оор issue хаадаг, бусад салааны commit нэгтгэгдэх хүртэл хүлээнэ. Гуравдугаарт, хэлбэр буруу: “fixes #1” зөв, “fixes issue 1” эсвэл “fixes#1” ажиллахгүй, “#” тэмдэг болон дугаар хамт, түлхүүр үгийн дараа зайтай байх ёстой. Хэрвээ commit аль хэдийн push хийгдсэн бол issue-г гараар хааж, сэтгэгдэлд commit-ын hash-ийг бичиж болно, GitHub hash-ийг холбоос болгоно.

Буруу issue хаагдах. Commit message-д дугаараа андуурч бичвэл, жишээ нь “fixes #2”, буруу issue хаагдана. Тэр issue хуудсанд очиж “Reopen issue” дарна уу. Commit message-ийг push хийснийх нь дараа засах боломжгүй гэдгийг 4.4 дүгээр хичээлээс санаж байгаа, тиймээс зөв issue-г гараар хааж, сэтгэгдэл бичнэ.

Дугаарыг зөвхөн дурдах. Хэрвээ commit message-д түлхүүр үггүйгээр зөвхөн “#1” гэж бичвэл, жишээ нь “Refactor average, related to #1”, GitHub issue-г хаахгүй, гэхдээ issue хуудсанд энэ commit-ыг дурдсан холбоос нэмнэ. Энэ нь issue дээр хэсэгчлэн ажилласан, гэхдээ бүрэн засаагүй үед хэрэгтэй.

Issues таб харагдахгүй байх. Хэрвээ repository-ийн табуудын дунд Issues байхгүй бол тэр боломж унтраалттай байна. Repository-ийн Settings табын “General” хэсэгт “Features” гэсэн дэд хэсэгт “Issues” сонголтыг идэвхжүүлнэ үү.

Public issue-д нууц мэдээлэл бичих. Public repository-ийн issue-үүд кодтой адил бүх хүнд харагдана. Алдааны мессеж хуулж тавихдаа тэнд нууц үг, API түлхүүр, хувийн өгөгдөл байгаа эсэхийг шалгаарай. 2.4 дүгээр хичээлийн .env-ийн дүрэм энд ч хамаатай: нууц мэдээллийг хэзээ ч issue-д бүү бичээрэй.

Товч дүгнэлт

Issue бол төсөлтэй холбоотой нэг алдаа, ажил, эсвэл санааг бүртгэдэг дугаартай хуудас бөгөөд repository-ийн Issues табд амьдардаг. Ажлын дунд олдсон алдааг шууд засахын оронд issue болгон бүртгэх нь анхны ажлыг тасалдуулахгүй, алдааг ч мартуулахгүй. Сайн гарчиг issue-г нээлгүйгээр ойлгуулдаг, алдааны тайлбарт юу болж байна, хэрхэн давтах, юу хүлээгдэж байсан гэсэн хэсгүүд, кодын блоктой алдааны мессеж байна. Тайлбар Markdown дэмждэг. Label-ууд, ялангуяа bug ба enhancement, issue-үүдийг ангилж, шүүх боломж олгоно. Commit message-д “fixes #1” гэх мэт түлхүүр үг бичиж main руу push хийвэл GitHub issue-г автоматаар хааж, commit болон issue-г хоёр чиглэлд холбоно. Issue-г гараар “completed” эсвэл “not planned” гэж хааж, хүссэн үедээ дахин нээж болно.

Дараагийн хичээлд GitHub-ийн хамгийн чухал хамтын ажиллагааны хэрэгсэл болох pull request-тэй танилцана. Салаан дээр хийсэн ажлаа шууд main-д нэгтгэхийн оронд GitHub дээр "энэ өөрчлөлтийг нэгтгэх хүсэлт" болгон нээж, өөрчлөлтөө өөрөө хянаж, дараа нь нэгтгэнэ. Энэ бүх мөчлөгийг ганцаараа туршиж, ирээдүйн багийн ажилд бэлдэнэ.