Ayini amafayela e-README nokuthi ungawasebenzisa kanjani kahle

Uma usebenza namaphrojekthi edijithali, ngokushesha noma kamuva uzothola ifayela elibizwa ngokuthi READMENakuba kungase kubonakale sengathi umbhalo olula, kubaluleke kakhulu kunalokho okubonakala ngakho: yi- incwadi yesembozo sephrojekthi yakho, iphuzu lokuqala lokungena kunoma ubani ofuna ukwazi ukuthi wenzeni, ukuthi angalisebenzisa kanjani, nokuthi liyakufanelekela yini isikhathi sakhe.

Ezweni lokuthuthukiswa kwesofthiwe, isayensi yedatha, noma ngisho nasemsebenzini wezemfundo kanye namaphrojekthi okubambisana, I-README ibhalwe kahle Kukusindisa isikhathi, kuvimbela amaphutha, futhi kwenza kube lula ngabanye (noma ngisho nawe ngokwakho ezinyangeni ezimbalwa) ukuqonda ngokushesha inhloso yephrojekthi. Ake sibheke kabanzi ukuthi ayini amafayela e-README, ahloselwe ini, ukuthi kufanele afakwe ini, nokuthi ungawasebenzisa kanjani ngokugcwele.

Iyini ngempela ifayela le-README?

Ifayela le-README liyi- umbhalo ohambisana nephrojekthi yedijithali Umgomo wayo oyinhloko ukuchaza ngokucacile ukuthi iphrojekthi iquketheni, ukuthi yenzelwe ini, nokuthi isetshenziswa kanjani. Uma ihunyushwa ngokwezwi nezwi, ingaba yinto efana nokuthi "ngifunde," futhi yilowo kanye umsebenzi wayo: ukuba yinto yokuqala umuntu ayifundayo lapho evula indawo yokugcina idatha, ifolda yedatha, noma iphakheji yesofthiwe.

Lolu hlobo lwefayela lungagcinwa ngezindlela ezahlukene amafomethi ombhalo: kusukela kwakudala readme.txt (umbhalo ocacile) kuze kufike ku- fundame.doc, fundame.1st noma izandiso ezingavamile kakhulu ezifana .meIfomethi ethile ivame ukushintshwa ukuze uhlelo lokusebenza kanye nohlelo oluzoboniswa ngaloukuze noma yimuphi umsebenzisi akwazi ukuvula nokufunda ifayela ngaphandle kwezinkinga.

Namuhla, ikakhulukazi kumaphrojekthi esofthiwe kanye nama-code repository, ifomethi evame kakhulu yi- README.mdIsandiso se-.md sibonisa ukuthi ifayela libhalwe nge- UkuphawulaI-HTML ulimi olulula kakhulu olukuvumela ukuthi uguqule umbhalo ube yi-HTML usebenzisa izimpawu ezimbalwa zokufometha. Lokhu kwenza kube lula ukufometha okuqukethwe. kulula ukuyifunda kokubili ngendlela eluhlaza neyihunyushwe kuwebhungaphezu kokuvumela izihloko, uhlu, izixhumanisi, amathebula, izithombe nokuningi ngaphandle kwezinkinga.

I-README ehlelwe kahle inikeza umsebenzisi noma umnikeli i- isifinyezo esiphelele nesiqondakalayo sephrojekthiAkuhlosiwe ukuba kube umbhalo ophelele, kodwa kube umhlahlandlela osebenzayo: ukuthi iphrojekthi yenzani, kungani iwusizo, ukuthi ingaqala kanjani ukuyisebenzisa nokuthi ungalutholaphi ulwazi olwengeziwe uma ludingeka.

Emkhakheni wedatha, isibonelo ezindaweni zokugcina idatha, kuvamile kakhulu ukuthi i-README (ngezinye izikhathi ibe yifomethi) ibe readme.txt) ukuqoqa Ulwazi olujwayelekile, ubunikazi bombhali, amagama angukhiye, ukumbozwa kwendawo kanye nesikhathi, ilayisensi yokusebenzisa kanye nendlela yokwenza izinto esetshenziswa ukukhiqiza noma ukuqoqa idatha, kanye Isofthiwe enconyiwe yokusebenza nabo.

Umlando omfushane kanye nokusetshenziswa okujwayelekile kwamafayela e-README

Nakuba namuhla sizihlanganisa kakhulu namapulatifomu afana neGitHub, umkhuba wokufaka ifayela le-README kumaphakheji esofthiwe uvela ku- emashumini eminyaka edluleKunezibonelo ezibhaliwe ezisukela emuva ku- maphakathi nawo-70, lapho izinhlelo zase zivele zisatshalaliswa ngedokhumenti encane echaza okuqukethwe kwazo kanye nokusetshenziswa kwazo.

Ngokuhamba kwesikhathi, lo mkhuba wasungulwa kangangokuthi Izindinganiso Zokubhala Amakhodi ze-GNU (izindinganiso zokubhala ikhodi ze-GNU) ifayela le-README libhekwa njengeliyi- imfunekoLezi zindinganiso zathonya kakhulu uhlelo lwesofthiwe yamahhala futhi zafaka isandla ekwenzeni ifayela le-README licishe libe yimpoqo kunoma yiliphi iphakheji yesofthiwe engathi sína.

Lapho iwebhu iba ipulatifomu ejwayelekile yokusabalalisa isofthiweAmaphrojekthi amaningi aqala ukuhambisa olunye ulwazi olwaluku-README ngaphambilini (amabhukwana, ilayisensi, izindaba, njll.) kumawebhusayithi, ama-wiki, noma iphakheji yekhodi yomthombo we-tarballNoma kunjalo, ifayela le-README alikaze linyamalale: ezimweni eziningi lahlala linjalo isifinyezo sendawoyize ngezinye izikhathi kwakuhlala kungaphelele uma kuqhathaniswa namadokhumenti aku-inthanethi.

Ukuthandwa kwezinkundla ezifana GitHub Futhi imizamo yemiphakathi yesofthiwe yamahhala esimeme ibuyisele amafayela e-README phambili. Ku-GitHub, isibonelo, uma indawo yokugcina iqukethe ifayela le-README kufolda yempande, uhlelo luzolifaka ngokuzenzakalelayo. Iguqula ngokuzenzakalelayo ibe yi-HTML bese iyibonisa ekhasini eliyisiqalo yephrojekthi, ngakho-ke yinto yokuqala oyibonayo uma ungena.

Ngaphezu kwalokho, umqondo "wefayela le-readme" ngezinye izikhathi usetshenziswa ku- okujwayelekile Ukubhekisela kunoma iyiphi idokhumenti emfushane echaza okuqukethwe yifolda noma iphrojekthi, noma ngabe ifayela alibizwa ngokuthi i-README ngqo. Amaphrojekthi amaningi esofthiwe yamahhala asabalalisa isethi ejwayelekile yamafayela kanye ne-README, ngalinye linomsebenzi ochazwe kahle.

Amafayela ajwayelekile ahambisana ne-README

Kumaphrojekthi alandela izindinganiso ezifana nokuthi Amazinga e-Gnits noma lezo ezikhiqizwe ngamathuluzi anjenge Ama-GNU AutotoolsNgaphezu kwe-README eyinhloko, kuvamile ukuthola amanye amafayela ombhalo anikeza ulwazi olwengeziwe lwephrojekthi. Amanye ajwayelekile kakhulu yilawa:

• README: ulwazi olujwayelekile mayelana nephrojekthi, inhloso kanye nombono jikelele.
• AUTHORS: uhlu lwababhali abayinhloko noma abahlanganyeli.
• NGENXA: ukubonga abantu noma izikhungo ezisizile.
• IZINGUQUKO: ilogi yokushintsha enemininingwane, eyenzelwe ngokuyinhloko onjiniyela.
• IZINDABA: ilogi yoshintsho emfushane neqondakalayo yabasebenzisi bokugcina.
• FAKA: imiyalelo ethile yokufaka kanye nezidingo zobuchwepheshe.
• UKUKOPISHA / ILAYISENSI: umbhalo welayisensi yesofthiwe yokusetshenziswa nokusatshalaliswa.
• IZIMBALIAmaphutha aziwayo nezindlela zokubika ngendlela efanele.
• Imibuzo Evame UkubuzwaImibuzo evame ukubuzwa kanye nezimpendulo zayo.
• Konke: uhlu lwemisebenzi elindile kanye nentuthuko ehleliwe yesikhathi esizayo.

Yonke le mibhalo, kanye nefomu le-README, uhlaka lwemibhalo eyisisekelo amaphakheji amaningi. Kwezinye izimo, olunye lwalolu lwazi lukopishwa kokubili endaweni yokugcina kanye nakuwebhusayithi yephrojekthi ukuze kube lula ukufinyelela kusuka eziteshini ezahlukene.

Indima ye-README ku-GitHub nakwamanye amapulatifomu afanayo

Ku-GitHub, ifayela le-README lidlala indima evelele kakhulu. Okokuqala, ngokuvamile liyi- into yokuqala umuntu ayibonayo lokho kuvakasha indawo yakho yokugcina impahlaUma ifayela lenziwe kahle, ngemizuzwana embalwa kuzocaca ukuthi lenzani iphrojekthi, kungani ingase ibe nesithakazelo, ukuthi ingaqalwa kanjani futhi isebenze, nokuthi ubani obangela lokho.

I-GitHub ibona ngokuzenzakalelayo ifayela le-README uma libekwe ezindaweni ezithile zokugcina. Uma ulifaka kufolda .github, ku umkhombandlela wezimpande noma kufolda docsipulatifomu iyayibona futhi iboniswa ngokugqamile kubavakashi. Uma kunamafayela amaningi e-README, i-GitHub ilandela i- ukuhleleka kokubalulekile: ukusesha kokuqala ku .github, bese kuba empandeni bese kuba ekugcineni docs.

Ngaphezu kwalokho, uma udala indawo yokugcina umphakathi enegama elifana ncamashi nelakho igama lomsebenzisi Futhi uma ungeza ifayela le-README kufolda yempande, lelo fayela liba ifayela lakho le-README ngokuzenzakalelayo. Iphrofayela ye-READMEIboniswa ekhasini lakho lomsebenzisi, okuvumela ukuthi udale isigaba sesethulo esenziwe ngokwezifiso usebenzisa i-GitHub Flavored Markdown.

Uma i-README (noma yiliphi ifayela le-.md) ibukwa ku-GitHub, ipulatifomu ikhiqiza ngokuzenzakalelayo i- Okuqukethwe ngokusekelwe ezihlokweni zedokhumenti. Ungabuka lolu hlu ngokuchofoza isithonjana esithi "Uhlaka", okwenza kube lula kakhulu ukuzulazula kumafayela amade e-README anezigaba eziningi.

I-GitHub ivumela futhi xhumanisa ngqo nezigaba ezithileIsihloko ngasinye sikhiqiza ngokuzenzakalelayo i-anchor; ukumane uzulazule phezu kwesihloko kuzoveza isithonjana sesixhumanisi. Lokhu kukuvumela ukuthi wabelane ngama-URL akhomba ngqo esigabeni esithile se-README ofuna ukusigqamisa (isibonelo, isigaba sokufaka noma seminikelo).

Kunemininingwane eyodwa ebalulekile esebenzayo: ngezizathu zokusebenza, uma i-README yakho idlula i- 500KB ngobukhulu, i-GitHub izonciphisa okuqukethwe Kusukela kulelo phuzu kuqhubeke ekubukeni okuhunyushiwe. Ngakho-ke, kunconywa ukubhukha i-README ngolwazi olubalulekile bese uhambisa izifundo ezinde noma izincwadi zemiyalelo kuma-wiki noma kumadokhumenti ahlukene.

Fometha futhi uxhumanise ngaphakathi kwe-README

Ukuze i-README ibe lula ukuyinakekela futhi isebenze kahle kokubili ku-GitHub kanye nama-clones endawo, kutuswa ukuthi usebenzise izixhumanisi ezihlobene kanye nezindlela zesithombe maqondana nefayela lapho zitholakala khona. Ngakho-ke, isibonelo, uma unefayela le-README kufolda yempande kanye nedokhumenti docs/CONTRIBUTING.mdIsixhumanisi esingaphakathi kwe-README singabukeka kanje: (docs/CONTRIBUTING.md).

Lolu hlobo lwesixhumanisi esihlobene lusho ukuthi lapho ushintsha amagatsha noma uhlanganisa indawo yokugcina, imizila iyaqhubeka nokusebenza kahle ngaphandle kwesidingo sokuzishintsha. I-GitHub iguqula ngaphakathi lezi zindlela ukuze zikhombe inguqulo yefayela efanele ngokusekelwe egatsheni elibonisiwe. Izindlela eziqala ngo /ezihunyushwa ngokuphathelene nempande yokugcina, kanye nabaqhubi abavamile abafana ./ o ../.

Kubalulekile ukuthi umbhalo wesixhumanisi Gcina isixhumanisi sisemgqeni owodwa, njengoba ukusihlukanisa phakathi kwemigqa eminingi kungabangela ukuthi singasebenzi kahle. Ngaphezu kwalokho, gwema izixhumanisi eziphelele kumafayela angaphakathi okugcina idatha, njengoba lezi zingaphuka uma i-URL eyisisekelo ishintsha noma kudalwa ifoloko.

Ngokuphathelene nobubanzi bombhalo, kubalulekile ukukhumbula ukuthi i-README kufanele iqukathe kuphela ulwazi olubalulekile okufanele uqale ukulusebenzisa nokufaka isandla kuphrojekthi. Ukuze uthole imibhalo ebanzi (amabhukwana abasebenzisi, iziqondiso eziphelele ze-API, njll.), kuhlanzekile ukusebenzisa wiki noma uhlelo oluhlukile lokubhala imibhalo, oluxhumanisa ne-README uqobo.

Iyini injongo yangempela yefayela le-README?

Ngaphandle kwethiyori, ifayela le-README lisebenza ngokoqobo njenge umhlahlandlela wokuqala kanye nendawo yokubhekiselaAkuhlosiwe ukuthatha indawo yamadokhumenti asemthethweni abanzi, kodwa kunalokho ukunikeza incazelo ehlelekile nesebenzayo yezici ezibaluleke kakhulu zephrojekthi.

Phakathi kokusetshenziswa kwayo okuvame kakhulu yile: chaza inhloso yephrojekthi, chaza ukuthi ihlanganisa yiphi idatha noma amafayela, ubonise ukuthi ungaqala kanjani ukuyisebenzisa, futhi ucacise izidingo zobuchwepheshe ezibalulekile kanye gwema amaphutha abangelwa ukusetshenziswa okungafaneleUma abasebenzisi abaningi besebenza kukhodi noma idatha efanayo, i-README ecacile igcina imibuzo ephindaphindwayo engapheli.

Kumaphrojekthi ahlanganyelwe, ikakhulukazi emaqenjini amakhulu noma emiphakathini evulekile, i-README cishe iyi- ingxenye yengqalasizinda yokuxhumanaKusebenza ukuvumelanisa okulindelwe, kubonise izinga lokuvuthwa kwephrojekthi, kuchaze ukuthi umuntu unikela kanjani, futhi kucacise ukuthi yiluphi usizo olunikezwayo (uma lukhona).

Ngisho nasemaphrojekthini akho, noma ngabe uzosebenza kuwo kuphela, i-README ebhalwe kahle isebenza njenge- inkumbulo yesikhathi esideNgokuhamba kwesikhathi kulula ukukhohlwa izinqumo, ukuncika, noma izinyathelo zokufaka; ukuba nakho kubhaliwe kukusindisa ekubeni "uphinde uthole" iphrojekthi yakho ezinyangeni ezizayo.

Ngakho-ke, i-README akuyona nje into ehlelekile: iyithuluzi eliwusizo elithuthukisayo inhlangano, ukuxhumana kanye nokugcinwa kwayo yanoma yiluphi uhlobo lwephrojekthi yedijithali.

Kunini lapho kufaneleka khona ukudala ifayela le-README?

Impendulo emfushane iwukuthi kungumqondo omuhle ukudala ifayela le-README. noma nini lapho kukhona iphrojekthi ezosetshenziswa, ibuyekezwe, noma inakekelwe ngomunye umuntu ongeyena umdali wokuqala… futhi lokho kufaka phakathi wena wesikhathi esizayo. Akudingeki kube yindawo yokugcina enkulu yomthombo ovulekile: kudinga nje ukuba nobunzima noma ukuthi okuqukethwe kuphakamise imibuzo.

Ezinye izibonelo lapho ifayela le-README liwusizo khona kakhulu yilezi: amaphrojekthi ewebhu noma okuhlelalapho kunconywa khona ukuchaza izidingo, izinqubo zokuthuthukisa, imiyalo yokuqalisa, kanye nendawo yokusebenza kwesikhathi. Kuyathakazelisa kakhulu futhi ku amafolda anedatha ebalulekileukucacisa ukuthi leyo datha imelani, imvelaphi yayo kanye nemikhawulo engaba khona.

Ezinye izimo ezijwayelekile yilezi: amawebhusayithi abanjwe ekusingatheniokuvame ukufaka i-README enemiyalelo yokusetshenziswa, noma imisebenzi yezemfundo kanye neyobuchwepheshe, lapho i-README ingachaza khona izikripthi, izivivinyo, izinguqulo zamathuluzi asetshenzisiwe, noma indlela yokukhiqiza kabusha imiphumela.

En amaphrojekthi ngokubambisanaKungakhathaliseki ukuthi ingaphakathi noma yomphakathi, i-README cishe iyimpoqo. Isiza abantu abasha ukujoyina iphrojekthi ngokushelela futhi isebenza njengereferensi ehlanganyelwe yokugcina amazinga okusetshenziswa kanye neminikelo ahambisanayo phakathi kwabo bonke abathintekayo.

Yiluphi ulwazi okufanele i-README enhle iluqukathe?

I-README esebenzayo akudingeki ibe yinde, kodwa kudingeka ibe njalo ihlelwe kahle futhi icacile kakhuluKukhona ulwazi oluyisisekelo okufanele lufakwe cishe njalo, kanye nokunye okuqukethwe okukhethwa kukho okwengeza inani elikhulu kuye ngohlobo lwephrojekthi.

Okungenani, izindawo zokugcina eziningi ezibhalwe kahle kanye namaphakheji afaka phakathi igama lephrojekthi, eyodwa incazelo emfushane yenhlosoisifinyezo sokuqukethwe kwenqolobane, Imiyalelo yokuyisebenzisa noma yokuyifaka kanye nezidingo ezibalulekile (ukuncika, inguqulo yolimi oluncane, uhlelo lokusebenza, njll.).

Kunconywa kakhulu futhi ukwengeza ezinye indlela yokuxhumana noma yokusekelaNgisho noma kuyi-imeyili noma isixhumanisi sesigaba esithi "Izinkinga" sendawo yokugcina izinto, lokhu kuqondisa noma ubani ohlangabezana nezinkinga ngokuthi angazibika kuphi futhi kanjani, esikhundleni sokumshiya elahlekile futhi engaqiniseki ukuthi axhumane nobani.

Ngaphezu kwezisekelo, kuvame ukuba wusizo ukufaka ulwazi mayelana usuku lokudala noma inguqulo okwamanje, uhlu lwababhali noma amaqembu anesibopho, ilayisense lokusebenzisa kanye nanoma yiziphi izaziso ezifanele mayelana nokusetshenziswa kwedatha noma ikhodi (isibonelo, uma kuyinguqulo yokuhlola noma engafanele ukukhiqizwa).

Ukuhleleka nakho kuthinta ukufundeka: ulwazi olubaluleke kakhulu (ukuthi iphrojekthi iyini, ihloselwe ini, ukuthi isetshenziswa kanjani) kufanele luvele kuqala. ekuqaleni kwedokhumentiukushiya imininingwane yesibili, amakhredithi anwetshiwe, noma amanothi omlando ukuze asetshenziswe kamuva. Ngale ndlela, umuntu ophequlula nje angathola umbono ocacile ngokubuka ngokushesha.

Okuqukethwe okuvamile kwe-README kusofthiwe

Kumaphrojekthi esofthiwe, amafayela e-README avame ukuhamba ibanga elide futhi afaka amabhlogo amaningana engeziwe e-theme. Ezimweni eziningi, ifayela lifingqa kafushane imiyalo yokusetha, imiyalelo yokufaka, imiyalelo eyisisekelo yokusetshenziswa, a i-manifesto yefayela (chaza ukuthi ifolda ngayinye ebalulekile ihloselwe ini) kanye nesifinyezo selayisensi.

Kuvamile futhi ukufaka isigaba esine- ulwazi mayelana nonjiniyela noma ithimba, izindlela ezingaba khona zokufaka isandla kuphrojekthi, uhlu lwamaphutha aziwayo, kanye nomhlahlandlela omfushane wokuxazulula izinkinga ezivamile. Konke lokhu kusiza noma ubani ovakashela indawo yokugcina izinto ukuba abe umbono womhlaba wonke nosebenzayo ngaphandle kwesidingo sokusesha kwenye indawo.

Kwezinye izimo, i-README ingaqukatha isici esincane Shintsha iLog noma ukhombe ifayela langaphandle le-CHANGELOG. Kuvamile futhi ukufaka isigaba esithi "Izindaba" noma esithi "Yini Entsha" esigqamisa izinguquko ezifanele phakathi kwezinguqulo, ikakhulukazi lapho izilaleli eziqondiwe zingabasebenzisi bokugcina kunokuba kube onjiniyela.

Uma kukhulunywa ngezindawo zokugcina ulwazi noma zedatha, ngaphezu kwencazelo yokuqukethwe, amathempulethi amaningi ancoma ukuchaza indlela yokuqoqa noma yokukhiqiza idatha, okuguquguqukayo okufakiwe, ububanzi besikhathi kanye nobendawo yolwazi, kanye nanoma yimiphi imikhawulo efanele ekusetshenzisweni noma ekuhunyushweni.

I-README njengethuluzi lokuxhumana ku-GitHub

Uma ulayisha iphrojekthi ku-GitHub, i-README ayigcini nje ngokuba yidokhumenti, kodwa futhi iba yi- isici sokuxhumana kanye nesethuloEqinisweni, ipulatifomu ngokwayo incoma ukwengeza i-README kunoma iyiphi indawo yokugcina umphakathi ukusiza izivakashi ziqonde ngokushesha ukuthi iphrojekthi imayelana nani.

Ungasebenzisa i-README ukuchaza lokho okwenziwa yiphrojekthiKungani kungaba wusizo, ungaqala kanjani (isibonelo, ngesigaba esithi "Ukuqala"), ukuthi ungalutholaphi usizo (izinkinga, amaforamu, ingxoxo, njll.), nokuthi ubani ogcina ikhodi ngenkuthalo. Konke lokhu kuthonya ikhwalithi ebonwayo kanye nokwethenjwa okwenziwa yi-repository.

Ezimweni eziningi, abathuthukisi basebenzisa izindawo zabo zokugcina ze-GitHub njenge Iphothifoliyo yobungcwetiKulesi simo, ama-README aklanywe kahle enza umehluko omkhulu: avumela abaqashi noma abanye abantu abanentshisekelo ukuthi babone, ngokubuka nje, ububanzi bephrojekthi, ubuchwepheshe obusetshenzisiwe, kanye nezindlela zokusebenza zombhali.

Uma inhloso yakho ingekhona ukuheha iminikelo noma ukukhuthaza indawo yokugcina (isibonelo, uma kuyiphrojekthi yangasese noma yangaphakathi kakhulu), i-README enemininingwane eminingi ayiphoqelekile. Noma kunjalo, ngokuvamile kuyasebenza ukugcina okungenani eyodwa imibhalo eyisisekelo eyisisekelo ukusetshenziswa komuntu siqu kanye neqembu.

I-GitHub iphinde inikeze ezinye izinsiza ezithile ezihlobene ne-README: ikhiqiza ngokuzenzakalelayo inkomba, isekela amabheji nezithonjana, futhi ikuvumela ukuthi ufake izithombe, ama-GIF, noma amavidiyo ukuze ubonise iphrojekthi. Uma zisetshenziswa ngempumelelo, zonke lezi zinto zingenza i-README isebenze kangcono. kukhanga kakhudlwana futhi kulula ukuzulazula.

Indlela yokuhlela nokuthuthukisa i-README yakho

Uma kuhlaziywa izindawo zokugcina ezidumile (isibonelo, amaphrojekthi avela ezinhlanganweni ezinkulu zobuchwepheshe noma izinhlangano zesikhala), kuyaphawuleka ukuthi amafayela abo e-README avame ukwabelana ngenani elithile amaphethini avamileyize iphrojekthi ngayinye igcina ubunikazi bayo obubonakalayo nobokuqukethwe.

Kuvamile ukuthola isihloko esicacile kanye nesithombe esingaba sesembozo (njengelogo noma ibhanela lephrojekthi), kulandelwe amabheji athile afingqa isimo sephrojekthi, ilayisensi, inguqulo yamanje, noma isimo sokuhlola. Bese kuba khona i- incazelo yephrojekthi, isigaba ngesimo (esizinzile, esisathuthukiswa, esivivinywayo, njll.) kanye nesigaba esinemiboniso noma izithombe-skrini.

Kuvamile futhi ukuthola ibhlogo eline- ukufinyelela kuphrojekthi (izixhumanisi zenguqulo esetshenzisiwe, amadokhumenti, namaphakheji ashicilelwe), uhlu lobuchwepheshe obusetshenzisiwe, izigaba ezinikezelwe kubanikeli, onjiniyela, kanye, vele, shiyaLezi zinto zisiza i-README ukuthi isebenze njengomhlahlandlela osheshayo wabasebenzisi kanye nekhadi lebhizinisi lalabo abangaba negalelo.

Ngokuphathelene nomklamo, yize sikhuluma ngefayela lombhalo, kunendawo eyanele yokwenza lifundeke kalula: sebenzisa izihloko ezihlelwe kahle, uhlu oluhleliwe nolungahlelwanga, amathebula lapho kufaneleka khona, kanye Umbhalo ogqamile ogqamisa imibono eyinhlokoKu-Markdown, ungafaka nezithombe, ama-GIF, kanye nemihlobiso emincane (njenge-emoji) ukuze kube lula ukuyisebenzisa, uhlale ukhumbula ukucaca.

Icebo elixoxwa kancane ukuthi uhlale ubhala ucabanga ngomuntu Akazi lutho nhlobo ngalo msebenzi.Lokhu kusho ukugwema ukucabanga ngolwazi lwangaphambilini, ukusebenzisa ulimi olucacile noluqondile, nokucacisa amagama obuchwepheshe ngesikhathi sokuqala avela. Futhi, vele, ukugcina i-README ivuselelwa noma nini lapho kukhona okushintshayo kuphrojekthi.

Ilayisensi, iminikelo kanye nokubhala

Kumaphrojekthi omthombo ovulekile, ingxenye ebaluleke kakhulu ye-README yileyo enikezelwe ku- shiyaIkhodi yokushicilela endaweni yokugcina yomphakathi ayikwenzi ngokuzenzakalelayo kube yisofthiwe yamahhala; kubalulekile ukusho ngokucacile ukuthi ngaphansi kwaziphi izimo ingabhekwa njengesofthiwe yamahhala. ukusetshenziswa, ukuguqulwa, nokusatshalaliswa kabusha.

Umkhuba ovame kakhulu ukusebenzisa amalayisense aziwayo (i-MIT, i-Apache, i-GPL, i-Creative Commons ukuze uthole amadokhumenti, njll.) bese uxhumanisa ifayela le-README nefayela le-LICENSE noma i-COPYING lendawo yokugcina. Ngale ndlela, noma ubani onentshisekelo uyazi ngokushesha ukuthi angenzani ngekhodi nokuthi yiziphi izibopho zakhe (isibonelo, ukwabiwa, ukwabelana ngokufanayo, imikhawulo yesibopho, njll.).

Esinye isici esibalulekile ku-README evuthiwe yi- umhlahlandlela wokunikelaLesi sigaba sichaza indlela abanye abanganikela ngayo kuphrojekthi: iziqondiso zesitayela, inqubo yokuthumela izicelo zokudonsa, indlela yokubika amaphutha, ukuthi yiziphi izinhlobo zeminikelo ezamukelwayo, nokuthi umsebenzi uhlanganiswa kuphi. Ngezinye izikhathi lolu lwazi luqukethwe kufayela elihlukile le-CONTRIBUTING.md elixhunywe ku-README.

Kungumkhuba omuhle futhi ukwenza kubonakale abantu ngabanye kanye nonjiniyela abanikelayoAmanye amaphrojekthi afaka amathebula anezithombe namagama axhunywe kumaphrofayela awo, kanti amanye afaka ohlwini abasebenzisi abayinhloko. Lesi senzo asigcini nje ngokuqaphela umsebenzi kodwa futhi senza kube lula ukuxhumana ngqo uma othile edinga ukukhuluma nelungu leqembu elithile.

Okokugcina, kufanelekile ukunikezela imigqa embalwa ekuchazeni indlela yokuthola usizo Futhi yiziphi iziteshi ezikhona: Izinkinga ze-GitHub, amaforamu, uhlu lweposi, izingxoxo, njll. Uma iphrojekthi inganikezi ukwesekwa okusemthethweni, kuyasebenza futhi ukukubonisa ngokucacile lokhu ukuze kugwenywe ukungaqondani.

Ngazo zonke lezi zinto ezingenhla, ifayela le-README liba yingxenye ebalulekile yanoma iyiphi iphrojekthi yedijithali: Ichaza ukuthi iyini, isebenza kanjani, ubani oyinakekelayo, nokuthi ingasetshenziswa ngaphansi kwaziphi izimo.Ukunakekela okuqukethwe kwakho nokuhlala kunolwazi lwakamuva kuyitshalomali elincane elenza umehluko omkhulu endleleni abanye abantu ababona futhi basebenzise ngayo umsebenzi wakho.