Hogyan írjunk jó elkötelezettségű üzeneteket: Gyakorlati Git útmutató

Hasznos verzióelőzmények létrehozásához a csapatoknak először meg kell állapodniuk egy elkötelezett üzenet konvencióban. Ez vonatkozik a személyes projektekre is.

Nemrégiben a Hashnode-on megkérdeztem: "Melyik elkövetési üzenetet használja a munkahelyén?" és csodálatos válaszokat kaptam a felhasználókkal, akik elmagyarázták a munkahelyi és személyes projektjeikhez alkalmazott konvenciókat.

Melyik elkötelezett üzenetet használja a munkahelyén?

@hashnode //t.co/HewCBxRCbr

- BOLAJI @ (@iambolajiayo) 2019. november 25

Ebben a cikkben áttekintem, hogyan lehet jó elkötelező üzeneteket írni és miért kellene.

PS: Ez a cikk először itt jelent meg a blogomon.

Bevezetés a Git verziókezelésébe

A verzióvezérlő szoftver elengedhetetlen része a modern szoftverfejlesztői gyakorlatnak.

A Git messze a világon a legszélesebb körben alkalmazott verziókezelő rendszer. Ez egy elosztott és aktívan karbantartott nyílt forráskódú projekt, amelyet eredetileg 2005-ben fejlesztett ki Linus Torvalds, a Linux operációs rendszer kernének híres alkotója.

Új a Gitnél? Nézze meg a hivatalos kezdési útmutatót vagy ezt a diát egy korábbi beszélgetésemből, amelyet adtam.

Mi az a kötelezettségvállalási üzenet?

Az comm parancsot a helyi adattár változásainak mentésére használják a Git-ben végzett állomás után. Mielőtt azonban mentené a módosításokat a Gitbe, el kell mondania a Gitnek, mely módosításokat szeretné menteni, mivel rengeteg szerkesztést hajtott végre. Ennek nagyszerű módja az, ha egy kötelezettségvállalási üzenetet ad hozzá a változtatások azonosításához.

Commit Options

  • -m

Ez az opció állítja be az elkövetés üzenetét.

git add static/admin/config.yml git commit -m "Setup multiple roles for netlify-cms git gateway" 
  • -a vagy --minden

Ez az opció automatikusan bekapcsolja az összes (beleértve az új) nyomon követett, módosított vagy törölt fájlt.

git commit -a -m "Add a new role for netlify-cms git gateway" 
  • --módosít

Ez az opció átírja a legutóbbi elkötelezettséget bármely jelenleg végrehajtott változtatással vagy új kötelezettségvállalási üzenettel, és csak olyan végrehajtásokra szabad végrehajtani, amelyek még nem kerültek távoli adattárba.

git add . git commit --amend -m "Update roles for netlify-cms git gateway" 

Miért kellene jó elkötelező üzeneteket írni?

Mondhatod: "Ez csak egy személyes projekt." Igen, most egyedül dolgozol, de mi történik, ha egy csapattal dolgozol, vagy hozzájárulsz a nyílt forráskódhoz?

A jól kidolgozott Git elkötelező üzenet a legjobb módja annak, hogy a változás körülményeit közöljük a projekten dolgozó más fejlesztőkkel, sőt, jövőbeli önmagával is.

Megpróbálta már futni git logegyik régi projektjén, hogy megnézze azokat a "furcsa" elkötelező üzeneteket, amelyeket már a kezdetek óta használt? Nehéz megérteni, miért hajtott végre valamilyen változtatást a múltban, és azt kívánja, hogy olvassa el ezt a cikket korábban :).

A kötelezettségvállalási üzenetek képesek megfelelően kommunikálni, miért történt változás, és megérteni, ami hatékonyabbá teszi a fejlesztést és az együttműködést.

Hogyan írjunk elkötelezett üzeneteket a Git segítségével

Korábban csak git commit -m "Fix X to allow Y to use Z"személyes témáimban használtam csak témát és külön leírást. Ez nagyszerű az olyan kicsi és egyértelmű javításokhoz, mint például git commit -m "Fix typo in README.md, de szélesebb körű változások esetén további részleteket kell megadnia.

Szerkesztő módszer

Futtatás git commitüzenet vagy opció nélkül, és ez megnyitja az alapértelmezett szövegszerkesztőt egy elkötelező üzenet írásához.

Az "alapértelmezett" szerkesztő konfigurálása:

git config --global core.editor nano 

Ez konfigurálná a Git-t, hogy alapértelmezett szerkesztőként használja a nano-t. Cserélje le a "nano" szót "emacs" -ra, "vim" -re vagy bármilyen másra.

A megnyílt szerkesztőben az első sor a tárgy (rövid leírás), hagyjon utána üres sort, és minden más a kiterjesztett leírás (törzs).

Parancssori módszer

git commit -m "Subject" -m "Description..." 

Az első -mlehetőség a tárgy (rövid leírás), a következő pedig a kibővített leírás (törzs).

Hogyan lehet jó elkötelező üzeneteket írni

Különböző csapatok és fejlesztők számos konvenciót használnak a jó elkötelezettségű üzenetek írására. Csak néhány általános szabályt és tippet vázolok fel a kötelezettségvállalási üzenetek írására - neked kell eldöntened, hogy milyen konvenciót szeretnél követni. És ha egy vállalatnál dolgozik, vagy hozzájárul a nyílt forráskódhoz, akkor alkalmazkodnia kell a megállapodásukhoz :).

A következetesség érdekében használhatja az egyik megállapodást munkához, a másikat pedig személyes projektekhez, mivel valamikor munkahelyet cserélhet, és a konvenció is megváltozhat.

Ügyeljen arra, hogy megnézze ezt a szálat elképesztő elkötelezett üzenetekről, vagy adja hozzá a tiédet, hogy segítsen valakinek a döntésben.

Íme egy remek sablon egy jó elkötelezettségű üzenetről, amelyet eredetileg Tim pápa írt

Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here - Use a hanging indent If you use an issue tracker, add a reference(s) to them at the bottom, like so: Resolves: #123 

Nagyon jól néz ki, igaz? Így teheti szebbé a sajátját is:

  1. Adja meg az elkötelezettség típusát:
  • feat: Az új funkció, amelyet hozzáad egy adott alkalmazáshoz
  • fix: A bug fix
  • style: Feature and updates related to styling
  • refactor: Refactoring a specific section of the codebase
  • test: Everything related to testing
  • docs: Everything related to documentation
  • chore: Regular code maintenance.[ You can also use emojis to represent commit types]
  1. Separate the subject from the body with a blank line
  2. Your commit message should not contain any whitespace errors
  3. Remove unnecessary punctuation marks
  4. Do not end the subject line with a period
  5. Capitalize the subject line and each paragraph
  6. Use the imperative mood in the subject line
  7. Use the body to explain what changes you have made and why you made them.
  8. Do not assume the reviewer understands what the original problem was, ensure you add it.
  9. Do not think your code is self-explanatory
  10. Follow the commit convention defined by your team

Conclusion

The most important part of a commit message is that it should be clear and meaningful. In the long run, writing good commit messages shows how much of a collaborator you are. The benefits of writing good commit messages are not only limited to your team, but indeed expand to yourself and future contributors.

Want to learn more about Git and become a professional "version controller"? Check out these excellent resources:

  • //try.github.io/
  • //git-scm.com/book/en/v2
  • //www.git-tower.com/learn/
  • //learngitbranching.js.org/
  • //github.com/commitizen/cz-cli