Információs fájl létrehozása az adattár számára

  • Cikk

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

A Git-adattárnak rendelkeznie kell egy olvasófájllal, hogy a megtekintők tudják, mit csinál a kód, és hogyan kezdhetik el használni. Az olvasónak a következő közönséghez kell szólnia:

  • Azok a felhasználók, amelyek csak futtatni szeretnék a kódot.
  • A kódot összeállítani és tesztelni kívánó fejlesztők. A fejlesztők is felhasználók.
  • Azok a közreműködők, amelyek módosításokat szeretnének küldeni a kódba. A közreműködők fejlesztők és felhasználók is.

Egyszerű szöveg helyett írja be az olvasási szöveget a Markdownba. A Markdown segítségével egyszerűen formázhatja a szöveget, képeket is tartalmazhat, és szükség szerint további dokumentációra hivatkozhat az olvasóban.

Íme néhány nagyszerű olvasmány, amelyek ezt a formátumot használják, és mindhárom közönséghez szólnak referenciaként és inspirációként:

Bevezetés létrehozása

Kezdje el az olvasást a projekt leírását ismertető rövid magyarázattal. Ha a projekt rendelkezik felhasználói felülettel, képernyőképet vagy animált GIF-et adhat hozzá az introjához. Ha a kód egy másik alkalmazásra vagy tárra támaszkodik, mindenképpen adja meg ezeket a függőségeket a bevezetőben vagy közvetlenül alatta. Az olyan alkalmazásoknak és eszközöknek, amelyek csak bizonyos platformokon futnak, az olvasás jelen szakaszában fel kell jegyezniük az operációs rendszer támogatott verzióit.

Segítség a felhasználóknak az első lépésekhez

Útmutató a felhasználóknak a kód saját rendszeren való futtatásához az olvasás következő szakaszában. Koncentráljon a kód használatának első lépéseire. Csatolja az előfeltételként szükséges szoftverek szükséges verzióit, így a felhasználók könnyen elérhetik őket. Ha összetett beállítási lépésekkel rendelkezik, dokumentálja az olvasási eszközén kívüli lépéseket, és hivatkozik rájuk.

Mutasson rá, hogy hol szerezheti be a kód legújabb kiadását. A bináris telepítő vagy a kód csomagolóeszközökön keresztüli használatára vonatkozó utasítások a legjobbak. Ha a projekt egy kódtár vagy egy API felülete, helyezzen el egy kódrészletet, amely megjeleníti az alapszintű használatot, és megjeleníti a kódrészlet mintakimenetét.

Buildelési lépések megadása fejlesztőknek

Az olvasójegy következő szakaszában bemutathatja a fejlesztőknek, hogyan hozhatják létre a kódot az adattár friss klónjából, és futtathatnak minden belefoglalt tesztet. Végezze el az alábbi műveleteket:

  • Adjon meg részleteket a kód létrehozásához szükséges eszközökről, és dokumentálja azokat a lépéseket, amelyekkel konfigurálhatja őket egy tiszta build beszerzéséhez.
  • Bontsa ki a sűrű vagy összetett összeállítási utasításokat egy külön oldalra a dokumentációban, és szükség esetén hivatkozz rá.
  • Futtassa végig az utasításokat írás közben, hogy ellenőrizze, hogy az utasítások működnek-e egy új közreműködőnél.

Ne feledje, hogy az utasításokra támaszkodó fejlesztő ön lehet, miután egy ideig nem dolgozik egy projekten.

Adja meg a parancsokat a forráskódban megadott tesztelési esetek futtatásához a build sikeres befejezése után. A fejlesztők ezekre a tesztesetekre támaszkodva gondoskodnak arról, hogy ne törjék meg a kódot a módosítások során. A jó tesztesetek mintaként is szolgálnak, amelyeket a fejlesztők saját teszteseteik létrehozásához használhatnak új funkciók hozzáadásakor.

Segítség a felhasználók közreműködéséhez

Az olvasás utolsó szakasza segít a felhasználóknak és a fejlesztőknek abban, hogy részt vegyenek a problémák jelentésében, és ötleteket javasoljanak a kód jobbá tétele érdekében. A felhasználóknak olyan csatornákhoz kell kapcsolódniuk, ahol megnyithatják a hibákat, szolgáltatásokat kérhetnek, vagy segítséget kérhetnek a kód használatával.

A fejlesztőknek tudniuk kell, hogy milyen szabályokat kell követniük a módosításokhoz, például a kódolási/tesztelési irányelveket és a lekéréses kérelmekre vonatkozó követelményeket. Ha a lekéréses kérelmek elfogadásához vagy a közösségi magatartási kódex kikényszerítéséhez közreműködői szerződésre van szüksége, ezt a folyamatot ebben a szakaszban kell összekapcsolni vagy dokumentálni. Adja meg, hogy a kód milyen licenccel jelenik meg, és hivatkozik a licenc teljes szövegére.