Kako napisati dobre poruke o predaji: Praktični vodič za Git

Da bi stvorili korisnu povijest revizija, timovi bi se prvo trebali dogovoriti o konvenciji poruke urezivanja koja će se koristiti. To se odnosi i na osobne projekte.

Nedavno sam na Hashnodeu pitao: "Koju konvenciju poruke urezivanja koristite na poslu?" i dobio sam nevjerojatne odgovore s korisnicima koji objašnjavaju konvencije koje koriste na poslu i za svoje osobne projekte.

Koju konvenciju poruke predavanja koristite na poslu?

s @hashnode //t.co/HewCBxRCbr

- BOLAJI ✨ (@iambolajiayo) 25. studenog 2019

U ovom ću članku razmotriti kako pisati dobre poruke urezivanja i zašto biste to trebali učiniti.

PS: Ovaj je članak prvi put objavljen na mom blogu ovdje.

Uvod u kontrolu verzija s Gitom

Softver za kontrolu inačica važan je dio moderne prakse programera softvera.

Daleko je Git najrasprostranjeniji sustav kontrole verzija na svijetu. Riječ je o distribuiranom i aktivno održavanom projektu otvorenog koda koji je izvorno 2005. godine razvio Linus Torvalds, poznati tvorac jezgre operativnog sustava Linux.

Novi ste u Gitu? Pogledajte službeni vodič za početak ili ovaj dijapozitiv iz prošlog govora.

Što je poruka predavanja?

Naredba commit koristi se za spremanje promjena u lokalno spremište nakon postavljanja u Git. Međutim, prije nego što možete spremiti promjene u Git, morate reći Gitu koje promjene želite spremiti jer ste možda napravili gomilu uređivanja. Sjajan način da to učinite je dodavanjem poruke predavanja da biste identificirali vaše promjene.

Opcije predavanja

  • -m

Ova opcija postavlja poruku urezivanja.

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

Ova opcija automatski urezuje sve (uključujući nove) praćene, izmijenjene ili izbrisane datoteke.

git commit -a -m "Add a new role for netlify-cms git gateway" 
  • --promjenu

Ova opcija prepisuje posljednje urezivanje s bilo kojim trenutno izmijenjenim promjenama ili novom porukom urezivanja i trebala bi se izvoditi samo za urezi koji još nisu gurnuti u udaljeno spremište.

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

Zašto biste trebali pisati dobre poruke urezivanja?

Mogli biste reći: "To je samo osobni projekt." Da, sada radite sami, ali što se događa kada radite s timom ili doprinosite otvorenom kodu?

Dobro razrađena poruka Git commit-a najbolji je način da se kontekst o promjeni komunicira s drugim programerima koji rade na tom projektu i zapravo sa svojim budućim osobama.

Jeste li ikad pokušali pokrenuti git logneki od svojih starih projekata kako biste vidjeli "čudne" poruke urezivanja koje ste koristili od njegovog početka? Može biti teško razumjeti zašto ste unijeli neke promjene u prošlosti i poželjet ćete da ovaj članak pročitate ranije :).

Poruke predavanja mogu na odgovarajući način priopćiti zašto je došlo do promjene i razumijevanje koje razvoj i suradnju čini učinkovitijim.

Kako napisati poruke predavanja pomoću Gita

Prije toga, koristio sam samo git commit -m "Fix X to allow Y to use Z"svoje osobne projekte samo s temom i bez dodatnog opisa. Ovo je izvrsno za male i jasne popravke poput git commit -m "Fix typo in README.md, ali u slučaju opsežnijih promjena, trebali biste dodati neke dodatne pojedinosti.

Metoda urednika

Pokrenite se git commitbez poruke ili opcije i otvorit će se zadani uređivač teksta za pisanje poruke urezivanja.

Da biste konfigurirali "zadani" uređivač:

git config --global core.editor nano 

To bi konfiguriralo Git da koristi nano kao zadani uređivač. Zamijenite "nano" s "emacs", "vim" ili što već želite.

U otvorenom uređivaču prvi je redak tema (kratki opis), ostavite prazan redak nakon njega, a sve ostalo je prošireni opis (tijelo).

Metoda naredbenog retka

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

Prva -mopcija je tema (kratki opis), a sljedeća je prošireni opis (tijelo).

Kako napisati dobre poruke urezivanja

Postoji nekoliko konvencija koje različiti timovi i programeri koriste za pisanje dobrih poruka urezivanja. Iznijet ću samo neka opća pravila i savjete za pisanje poruka obvezivanja - morate odlučiti koju konvenciju želite slijediti. A ako radite u tvrtki ili doprinosite otvorenom kodu, morate se prilagoditi njihovoj konvenciji :).

Da biste bili dosljedni, jednu konvenciju možete koristiti za posao, a drugu za osobne projekte, jer nekada možete promijeniti posao, a konvencija se također može promijeniti.

Svakako pogledajte ovu nit za neke nevjerojatne konvencije poruka urezivanja ili dodajte svoju kako biste pomogli nekome da donese odluku.

Evo izvrsnog predloška dobre poruke urezivanja koje je izvorno napisao Tim Pope

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 

Izgleda sjajno, zar ne? Evo kako i vi možete učiniti svoj sjajnim:

  1. Navedite vrstu urezivanja:
  • feat: Nova značajka koju dodajete u određenu aplikaciju
  • 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