├── CODEOWNERS ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── README_az-AZ.MD ├── README_de-DE.md ├── README_es-AR.md ├── README_fa-IR.md ├── README_fr-FR.md ├── README_gr-GR.md ├── README_it-IT.md ├── README_ja-JP.md ├── README_ko-KR.md ├── README_pl-PL.md ├── README_pt-BR.md ├── README_ru-RU.md ├── README_tr-TR.md ├── README_ua-UA.md ├── README_vi-VN.md ├── README_zh-CN.md └── README_zh-TW.md /CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @RomuloOliveira 2 | README_de-DE.md @Ana06 3 | README_ua-UA.md @CODER591 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | First of all, thanks for the taking time to contribute and help people! 4 | 5 | This document contains a set of guidelines for contributing to the repository. These guidelines are intended to provide a clear and concise to help you to know where help is needed and how you can contribute to improve the guide. 6 | 7 | ## Where can I help? 8 | 9 | There are several ways to contribute. A contribution could happen both in the form of changes to the repository itself or through pull request reviews. Any kind of help would be appreciated. 10 | 11 | In special, I'd like to highlight and bring attention to help in the form of: 12 | 13 | - Fix of inconsistencies across languages 14 | - Grammar and spelling corrections 15 | - Improvement of source referencing (images, references, etc.) 16 | - Incorrect, inconsistent or incomplete information fixes 17 | - Pull request reviews 18 | - Translation to other languages 19 | 20 | ## Principles 21 | 22 | - **Consistency across languages over 100% correct grammar/spelling**: It's better to have some grammar and spelling errors than having outdated or specialized content for a single language. Use Google Translate or similar tools when needed. 23 | - **Best practices in this guide should aim to help, not to set rule-following blindly standards**: It's intended to provide resourceful guidelines to help people communicate in a better, concise and clear way. It's a mean to an end, not the end itself. 24 | - **One size does not fit all**: A project, team or company standards and agreements may override common practices. People may not agree 100% with all practices and it's ok. These things should not led to add or remove a guideline. Helping people should. 25 | - **Native speakers are owners, but two heads are better than one**: Pull request authors do the best they can, but this doesn't replaces a good review by another native speaker. 26 | 27 | Feel free to propose improvements if you have. 28 | 29 | ## Guidelines 30 | 31 | Try to follow these guidelines when contributing. They're not rules and I'll not strictly enforce them, although I may ask you to adapt your contribution according to it. 32 | 33 | Feel free to propose changes to the guidelines and use your best judgment. 34 | 35 | ### General guidelines 36 | 37 | - You may fork the project to make changes to the repository. See [this Github guide](https://guides.github.com/activities/forking/) explaining how to do it. 38 | - Use English for commit messages, issues and pull requests (both description and discussions). 39 | - Use the [best practices](https://github.com/RomuloOliveira/commit-messages-guide#good-practices) described in the guide. 40 | - Add `[PROPOSAL]` prefix to PR title when doing additions other than translations or corrections (e.g., [#31](https://github.com/RomuloOliveira/commit-messages-guide/pull/31)) 41 | - Github editor usually suggests a commit message like "Update file", add a description of your change in the commit body or change the title. 42 | - A good example: [7747659](https://github.com/RomuloOliveira/commit-messages-guide/commit/7747659824b83f6d07589daa66a67ee29fa60ddb) 43 | 44 | It worth noting again that the best practices described in this guide are _guidelines_ and not rules. I won't refuse your contribution nor nitpick your commit messages if you're not following them strictly. It aims to help. 45 | 46 | ### New translation checklist 47 | 48 | - Make sure you're working in the most updated branch. Rebase your code and fix conflicts when needed. 49 | - Make sure you've updated the [Available languages section](https://github.com/RomuloOliveira/commit-messages-guide#available-languages) section in (and only in) README.md. 50 | - Make sure you haven't included `Available languages` section in your translation (See [#31](https://github.com/RomuloOliveira/commit-messages-guide/pull/31)). 51 | 52 | ### Pull Request review process 53 | 54 | Preferably, there should be at least 1 review from a native speaker. All pull requests will stay open for a few days waiting for a review help. Translations that didn't had a thorough review by a native speakers should be merged in a couple days, though. 55 | 56 | All discussions should be resolved before a merge. Only [code owners](https://github.com/RomuloOliveira/commit-messages-guide/blob/master/CODEOWNERS) can do a merge. Native speakers have the authority to request changes in any pull request. 57 | 58 | Everything that applies to a native speaker also applies to a fluent writer. 59 | 60 | ## Author notes 61 | 62 | _by @RomuloOliveira_ 63 | 64 | I'm a Brazilian Portuguese native speaker still working on my English. I'll try to review all translations using Google Translate but a native speaker review is way more valuable. 65 | 66 | I'll open pull requests for significant changes and proposals, but I may commit directly to the master branch for minor fixes or changes that do not affect translations' content. 67 | 68 | Opinions and contents are my own and don't necessarily represent those of my current or former employers. 69 | 70 | ## Thanks 71 | 72 | Helping people is priceless and I thank every and each of you that contributed to this guide. 73 | -------------------------------------------------------------------------------- /README_de-DE.md: -------------------------------------------------------------------------------- 1 | # Commit Messages Guide 2 | 3 | [![Sag danke!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Ein Leitfaden, um die Wichtigkeit von Commit-Messages zu verstehen und diese richtig zu formulieren. 6 | 7 | Verstehe was ein Commit ist, warum es wichtig ist, eine gute Commit-Message zu schreiben, gute Praxis und ein paar Tipps, um eine saubere Commit-Historie zu planen oder vielleicht sogar nachträglich noch anzupassen. 8 | 9 | #### Hinweis des Übersetzers 10 | 11 | Auch wenn dies eine Übersetzung darstellen soll, empfiehlt es sich, alle Commit-Messages auf Englisch zu schreiben, deshalb sind die Beispiele nicht übersetzt. 12 | 13 | ## Was ist ein "Commit"? 14 | 15 | Ganz einfach beschrieben ist ein Commit eine Art _Schnappschuss_ deiner lokalen Dateien in deinem Repository (dein Projektordner). 16 | Im Gegensatz zur geläufigen Annahme [speichert Git nicht nur die Unterschiede in den Dateien, sondern immer die gesamte Datei (Quelle auf Englisch)](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences). 17 | Für Dateien, die sich von einem auf den anderen Commit nicht geändert haben, speichert Git lediglich einen Link zur einer bereits gespeicherten Version in einem vorangegangenen Commit. 18 | 19 | Die folgende Grafik zeigt wie Git die Daten mit der Zeit speichert. Jede "Version" meint hier einen Commit. 20 | 21 | ![](https://i.stack.imgur.com/AQ5TG.png) 22 | 23 | ## Warum sind Commit-Messages wichtig? 24 | 25 | - Um Code-Reviews zu beschleunigen und zu vereinfachen 26 | - Um die erzielte Änderung besser verstehen zu können 27 | - Um _die_ Gründe zu erläutern, die so nicht aus dem Code hervorgehen (Grundsatzentscheidungen) 28 | - Um zukünftigen Entwicklern zu helfen, zu verstehen, wie und warum Änderungen gemacht wurden – was die Fehlersuche und -behebung vereinfacht 29 | 30 | Um diese und noch mehr Vorteile möglichst effizient nutzen zu können, sollten wir uns an die folgenden Praktiken und Standards halten. 31 | 32 | ## Praktiken 33 | 34 | Dies sind Praktiken aus meiner eigenen Erfahrung, sowie aus anderen Artikeln/Anleitungen aus dem Internet. Wenn du noch mehr Tipps hast oder manche dieser Praktiken für nicht sinnvoll hältst, beantrage gerne eine Änderung via Pull Request. 35 | 36 | ### Imperativ verwenden 37 | 38 | ``` 39 | # Good 40 | Use InventoryBackendPool to retrieve inventory backend 41 | ``` 42 | 43 | ``` 44 | # Bad 45 | Used InventoryBackendPool to retrieve inventory backend 46 | ``` 47 | 48 | _Warum soll ich den Imperativ benutzen?_ 49 | 50 | Eine Commit-Message beschreibt was die Änderung tatsächlich **tut** – ihre Auswirkungen – nicht was vorher war. 51 | 52 | ### Große Anfangsbuchstaben 53 | 54 | ``` 55 | # Good 56 | Add `use` method to Credit model 57 | ``` 58 | 59 | ``` 60 | # Bad 61 | add `use` method to Credit model 62 | ``` 63 | 64 | Diese Regelung ergibt grammatikalisch schlichtweg Sinn, da man den grammatikalischen Regeln bzgl. Großbuchstaben am Satzanfang gerecht wird. 65 | 66 | Diese Regelung kann von Entwickler zu Entwickler, Team zu Team oder auch Sprache zu Sprache unterschiedlich sein. 67 | 68 | Großschreiben oder nicht, wichtig ist nur, dass man bei einer Variante bleibt. 69 | 70 | ### Versuche _genau_ zu beschreiben, was die Änderung macht, auch ohne dass man in den Code gucken muss. 71 | 72 | ``` 73 | # Good 74 | Add `use` method to Credit model 75 | 76 | ``` 77 | 78 | ``` 79 | # Bad 80 | Add `use` method 81 | ``` 82 | 83 | ``` 84 | # Good 85 | Increase left padding between textbox and layout frame 86 | ``` 87 | 88 | ``` 89 | # Bad 90 | Adjust css 91 | ``` 92 | 93 | Dies ist in vielen Situationen (z.B.: mehrere kleine Commits, Refactoring) sinnvoll, um besser zu verstehen, was sich der Entwickler gedacht hat. 94 | 95 | ### "Warum", "Wozu", "Wie" und andere Details gehören in die Beschreibung der Commit-Message 96 | 97 | ``` 98 | # Good 99 | Fix method name of InventoryBackend child classes 100 | 101 | Classes derived from InventoryBackend were not 102 | respecting the base class interface. 103 | 104 | It worked because cart was calling the backend implementation 105 | incorrectly. 106 | ``` 107 | 108 | ``` 109 | # Good 110 | Serialize and deserialize credits to json in Cart 111 | 112 | Convert the Credit instances to dict for two main reasons: 113 | 114 | - Pickle relies on file path for classes and we do not want to break up 115 | everything if a refactor is needed 116 | - Dict and built-in types are picklable by default 117 | ``` 118 | 119 | ``` 120 | # Good 121 | Add `use` method to Credit model 122 | 123 | Change from namedtuple to class because we need to 124 | setup a new attribute (in_use_amount) with a new value 125 | ``` 126 | 127 | Titel bzw. Betreff der Commit-Message und die Beschreibung müssen mit einer Leerzeile getrennt werden. Alle weiteren Leerzeilen oder Absätze werden als Teil der Beschreibung gewertet. 128 | 129 | Trenn- oder Aufzählungszeichen, wie z.B.: `-`, `*` oder `\` verbessern die Lesbarkeit der Beschreibung. 130 | 131 | ### Vermeide allgemeingültige oder kontextfreie Beschreibungen 132 | 133 | ``` 134 | # Bad 135 | Fix this 136 | 137 | Fix stuff 138 | 139 | It should work now 140 | 141 | Change stuff 142 | 143 | Adjust css 144 | ``` 145 | 146 | ### Limitiere die Länge der Commit-Message 147 | 148 | [Es wird empfohlen (Quelle in ENG)](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) maximal 50 Zeichen für den Titel/Betreff und 72 Zeichen für die Nachricht zu verwenden. 149 | 150 | ### Bleibe in einer Sprache 151 | 152 | Dies gilt vor allem für Entwickler, für die Englisch nicht die Muttersprache ist. Logischerweise sollte man sich immer dem etablierten Standard anpassen – ganz besonders bei Repositories mit Entwicklern aus vielen verschiedenen Ländern. 153 | 154 | Entscheide dich für eine Sprache und bleibe dabei. 155 | 156 | ``` 157 | # Good 158 | ababab Add `use` method to Credit model 159 | efefef Use InventoryBackendPool to retrieve inventory backend 160 | bebebe Fix method name of InventoryBackend child classes 161 | ``` 162 | 163 | ``` 164 | # Good (German example) 165 | ababab Fügt die `use` Funktion dem Credit Model hinzu 166 | efefef Nutzt den InventoryBackendPool um aufs Bestands-BackEnd zuzugreifen 167 | bebebe Korrigiert den Methodennamen der InventoryBackend Kind-Klassen 168 | ``` 169 | 170 | ``` 171 | # Bad (mixes English and German) 172 | ababab Fügt die `use` Funktion dem Credit Model hinzu 173 | efefef Add `use` method to Credit model 174 | cdcdcd Fix method name of InventoryBackend child classes 175 | ``` 176 | 177 | ### Template 178 | 179 | Das folgende Template, [im Original von Tim Pope (Quelle auf Englisch)](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), erschienen so auch in dem Buch [Pro Git Book (Quelle auf Englisch)](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 180 | 181 | ``` 182 | Summarize changes in around 50 characters or less 183 | 184 | More detailed explanatory text, if necessary. Wrap it to about 72 185 | characters or so. In some contexts, the first line is treated as the 186 | subject of the commit and the rest of the text as the body. The 187 | blank line separating the summary from the body is critical (unless 188 | you omit the body entirely); various tools like `log`, `shortlog` 189 | and `rebase` can get confused if you run the two together. 190 | 191 | Explain the problem that this commit is solving. Focus on why you 192 | are making this change as opposed to how (the code explains that). 193 | Are there side effects or other unintuitive consequences of this 194 | change? Here's the place to explain them. 195 | 196 | Further paragraphs come after blank lines. 197 | 198 | - Bullet points are okay, too 199 | 200 | - Typically a hyphen or asterisk is used for the bullet, preceded 201 | by a single space, with blank lines in between, but conventions 202 | vary here 203 | 204 | If you use an issue tracker, put references to them at the bottom, 205 | like this: 206 | 207 | Resolves: #123 208 | See also: #456, #789 209 | ``` 210 | 211 | ## Rebase vs _Merge_ 212 | 213 | Dieser Abschnitt ist ein **Tl;DR** des lesenswerten Artikels [Atlassian's article Merging vs. Rebasing (Quelle auf Englisch)](https://www.atlassian.com/git/tutorials/merging-vs-rebasing). 214 | 215 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 216 | 217 | ### Rebase 218 | 219 | **TL;DR:** Wendet die Änderungen des aktuellen Branches auf den Stand des Basis-Branches an. 220 | 221 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 222 | 223 | ### _Merge_ 224 | 225 | **TL;DR:** Erstellt einen neuen Commit, auch _Merge-Commit_, dieser führt die Änderungen beider Branches zusammen. 226 | 227 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 228 | 229 | ### Warum bevorzugen manche Entwickler rebase? 230 | 231 | Ich persönlich bevorzuge rebase. Gründe dafür sind unter anderem: 232 | 233 | * Es entsteht eine "saubere" Historie, ohne unnötige Merge-Commits. 234 | 235 | * _What you see is what you get_, z.B.: in eine Code-Review sieht man wirklich jeden Commit. Es sind keine Änderungen in Merge-Commits versteckt. 236 | * Jedes Zusammenführen von Code geschieht einzeln durch den Entwickler, so hat jeder Merge einen eigenen Commit mit einer entsprechenen Commit-Message. 237 | * Im Normalfall werden Merge-Commits in einer Code-Review nicht betrachtet. Hat jede Änderung/Zusammenführung einen eigenen Commit, kann man sicher sein, dass alles an der richtigen Stelle ist und betrachtet werden kann. 238 | 239 | ### Wann benutzt man squash 240 | 241 | Squash beschreibt eine Methode in der eine Reihe von Commits in einem einzelnen Commit zusammengefasst werden. 242 | 243 | Hilfreich bei z.B.: 244 | 245 | - dem Reduzieren von kleinen/kontextlosen Commits (Rechtschreibfehler, Formatierung, vergessene Änderungen) 246 | - dem Zusammenführen mehrerer Commits, die als Ganzes mehr Sinn ergeben 247 | - dem Neu-Verpacken von _work in progress_ Commits 248 | 249 | ### Wann sollte man rebase bzw. squash vermeiden 250 | 251 | Vermeiden Sie die Verwendung von Rebase und Squash in öffentlichen Commits oder in Branches, in denen mehrere Personen arbeiten. 252 | 253 | Rebase und Squash verändern die Historie der Commits und überschreiben bestehende Commits. Verwendet man rebase und squash auf Commits, die sich auf einen gemeinsam genutzten Branch befinden (d.h. Commits, die in ein Remote-Repository verschoben wurden oder von anderen Branches stammen), erzeugt man unötige Verwirrung. Darüber hinaus besteht die Gefahr, dass Andere ihre Änderungen (sowohl lokal als auch auf dem Remote) verlieren, aufgrund von unterschiedlichen Trees und anderen Konflikten. 254 | 255 | ## Hilfreiche Git Kommandos 256 | 257 | ### rebase -i 258 | 259 | Wird verwendet, um Commits zu squashen, Commit-Messages zu bearbeiten, Neuschreiben/Löschen/Neuordnen von Commits, usw. 260 | 261 | ``` 262 | pick 002a7cc Improve description and update document title 263 | pick 897f66d Add contributing section 264 | pick e9549cf Add a section of Available languages 265 | pick ec003aa Add "What is a commit" section" 266 | pick bbe5361 Add source referencing as a point of help wanted 267 | pick b71115e Add a section explaining the importance of commit messages 268 | pick 669bf2b Add "Good practices" section 269 | pick d8340d7 Add capitalization of first letter practice 270 | pick 925f42b Add a practice to encourage good descriptions 271 | pick be05171 Add a section showing good uses of message body 272 | pick d115bb8 Add generic messages and column limit sections 273 | pick 1693840 Add a section about language consistency 274 | pick 80c5f47 Add commit message template 275 | pick 8827962 Fix triple "m" typo 276 | pick 9b81c72 Add "Rebase vs Merge" section 277 | 278 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 279 | # 280 | # Commands: 281 | # p, pick = use commit 282 | # r, reword = use commit, but edit the commit message 283 | # e, edit = use commit, but stop for amending 284 | # s, squash = use commit, but meld into previous commit 285 | # f, fixup = like "squash", but discard this commit's log message 286 | # x, exec = run command (the rest of the line) using shell 287 | # d, drop = remove commit 288 | # 289 | # These lines can be re-ordered; they are executed from top to bottom. 290 | # 291 | # If you remove a line here THAT COMMIT WILL BE LOST. 292 | # 293 | # However, if you remove everything, the rebase will be aborted. 294 | # 295 | # Note that empty commits are commented out 296 | ``` 297 | 298 | ### fixup 299 | 300 | Wird verwendet, um Commits einfach anzupassen ohne ein komplexes Rebase durchzuführen. 301 | [Dieser Artikel (Quelle auf Englisch)](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) beschreibt mit Beispielen wie und wann man einen fixup durchführt. 302 | 303 | ### cherry-pick 304 | 305 | Sehr hilfreich, wenn man einen Commit der z.B. versehentlich im falschen Branch gepusht wurde, auf den richtigen Branch anwenden will, ohne diesen neuschreiben zu müssen. 306 | 307 | Beispiel: 308 | 309 | ``` 310 | $ git cherry-pick 790ab21 311 | [master 094d820] Fix English grammar in Contributing 312 | Date: Sun Feb 25 23:14:23 2018 -0300 313 | 1 file changed, 1 insertion(+), 1 deletion(-) 314 | ``` 315 | 316 | ### git add/checkout/reset [--patch | -p] 317 | 318 | Angenommen wir haben die folgenden offenen Änderungen: 319 | 320 | ```diff 321 | diff --git a/README.md b/README.md 322 | index 7b45277..6b1993c 100644 323 | --- a/README.md 324 | +++ b/README.md 325 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 326 | `` 327 | # Bad (mixes English and Portuguese) 328 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 329 | -efefef Add `use` method to Credit model 330 | cdcdcd Agora vai 331 | `` 332 | 333 | +### Template 334 | + 335 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in [Pro Git Book](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 336 | + 337 | ## Contributing 338 | 339 | Any kind of help would be appreciated. Example of topics that you can help me with: 340 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 341 | 342 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 343 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 344 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 345 | ``` 346 | 347 | Mit `git add -p` können wir nun ausschließlich die gewünschten Abschnitte zum Commit hinzufügen, ganz ohne dass wir bestehenden Code ändern müssen. Das ist hilfreich, um größere Änderungen in mehrere kleine Commits aufzuteilen oder um ungewollte Änderungen gezielt rückgängig zu machen. 348 | 349 | ``` 350 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 351 | Split into 2 hunks. 352 | ``` 353 | 354 | #### hunk 1 355 | 356 | ```diff 357 | @@ -186,7 +186,6 @@ 358 | `` 359 | # Bad (mixes English and Portuguese) 360 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 361 | -efefef Add `use` method to Credit model 362 | cdcdcd Agora vai 363 | `` 364 | 365 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 366 | ``` 367 | 368 | #### hunk 2 369 | 370 | ```diff 371 | @@ -190,6 +189,10 @@ 372 | `` 373 | cdcdcd Agora vai 374 | `` 375 | 376 | +### Template 377 | + 378 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in [Pro Git Book](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 379 | + 380 | ## Contributing 381 | 382 | Any kind of help would be appreciated. Example of topics that you can help me with: 383 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 384 | 385 | ``` 386 | 387 | #### hunk 3 388 | 389 | ```diff 390 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 391 | 392 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 393 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 394 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 395 | ``` 396 | 397 | ## Sonstiges Interessantes 398 | 399 | - https://whatthecommit.com/ 400 | - https://gitmoji.carloscuesta.me/ 401 | 402 | ## Hat es dir gefallen? 403 | 404 | [Sag danke!](https://saythanks.io/to/RomuloOliveira) 405 | 406 | ## Mitwirken 407 | 408 | Jede Art von Hilfe ist willkommen. Zum Beispiel zu den Themen: 409 | 410 | - Grammatik und Rechtschreibung 411 | - Übersetzung in andere Sprachen 412 | - Verbesserung der Quell-Referenzen 413 | - Falsche oder unvollständige Information 414 | 415 | ## Inspiration, Quellen und Lesenswertes 416 | 417 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 418 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 419 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 420 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 421 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 422 | -------------------------------------------------------------------------------- /README_es-AR.md: -------------------------------------------------------------------------------- 1 | # Guía de mensajes de commit 2 | 3 | [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Una guía para entender la importancia de los mensajes de commit y cómo escribirlos correctamente. 6 | 7 | Aquí vas a aprender qué es un commit, por qué es importente escribir buenos mensajes, buenas prácticas y algunos tips para planear y (re)escribir una buena historia de commits. 8 | 9 | ## ¿Qué es un "commit"? 10 | 11 | En una frase, un commit es una copia instantánea de los archivos escritos de tu repositorio local. 12 | En contra de lo que mucha gente cree, [git no guarda solo la diferencia entre los archivos, sino que guarda cada versión completa](https://git-scm.com/book/es/v2/Inicio---Sobre-el-Control-de-Versiones-Fundamentos-de-Git#_copias_instant%C3%A1neas_no_diferencias) 13 | Para los archivos que no cambian de un commit a otro, git guarda un enlace a la versión previa, idéntica al archivo guardado. 14 | 15 | La imagen a continuación muestra como git guarda datos a través del tiempo, entendiendo que cada "versión" es un commit: 16 | 17 | ![](https://i.stack.imgur.com/AQ5TG.png) 18 | 19 | ## ¿Por qué los mensajes de commit son importantes? 20 | 21 | - Para acelerar y dinamizar las revisiones de código 22 | - Para ayudar a entender los cambios 23 | - Para explicar los "por qué" que no pueden ser descritos solo con código 24 | - Para ayudar a los mantenedores futuros a entender por qué o cómo se hizo un cambio, facilitando la resolución de problemas y la depuración 25 | 26 | Para maximizar estos resultados se pueden usar las buenas prácticas y estándares descritos en la sección siguiente. 27 | 28 | ## Buenas prácticas 29 | 30 | Estas son algunas prácticas recolectadas desde mi experiencia, artículos de internet y otras guías. Si tienes otras (o estás en contra de alguna) siéntete libre de abrir un Pull Request y contribuir. 31 | 32 | ### Usa forma imperativa 33 | 34 | ``` 35 | # Good 36 | Use InventoryBackendPool to retrieve inventory backend 37 | ``` 38 | 39 | ``` 40 | # Bad 41 | Used InventoryBackendPool to retrieve inventory backend 42 | ``` 43 | 44 | _¿Pero por qué usar forma imperativa?_ 45 | 46 | Un mensaje de commit describe qué **hace** el cambio referenciado, su efecto, no qué se hizo. 47 | 48 | 49 | ### Primera letra en mayúscula 50 | 51 | ``` 52 | # Good 53 | Add `use` method to Credit model 54 | ``` 55 | 56 | ``` 57 | # Bad 58 | add `use` method to Credit model 59 | ``` 60 | 61 | El motivo detrás de esto es para seguir la regla gramatical que las oraciones deben comenzar en mayúsculas. 62 | 63 | El uso de esta práctica puede variar de persona a persona, de equipo a equipo, o incluso de idioma a idioma. 64 | Mayúsculas o no, es importante adherir a un solo estándar y respetarlo. 65 | 66 | ### Comunica qué hace el cambio sin necesidad de mirar al código fuente 67 | 68 | ``` 69 | # Good 70 | Add `use` method to Credit model 71 | 72 | ``` 73 | 74 | ``` 75 | # Bad 76 | Add `use` method 77 | ``` 78 | 79 | ``` 80 | # Good 81 | Increase left padding between textbox and layout frame 82 | ``` 83 | 84 | ``` 85 | # Bad 86 | Adjust css 87 | ``` 88 | 89 | Es muy útil para ayudar a los revisores a entender el razonamiento del autor de los cambios (por ejemplo, cuando hay muchos commits, muchos cambios y refactors) 90 | 91 | ### Usa el cuerpo del mensaje para explicar "por qué", "para qué", "cómo" y detalles adicionales 92 | 93 | ``` 94 | # Good 95 | Fix method name of InventoryBackend child classes 96 | 97 | Classes derived from InventoryBackend were not 98 | respecting the base class interface. 99 | 100 | It worked because cart was calling the backend implementation 101 | incorrectly. 102 | ``` 103 | 104 | ``` 105 | # Good 106 | Serialize and deserialize credits to json in Cart 107 | 108 | Convert the Credit instances to dict for two main reasons: 109 | 110 | - Pickle relies on file path for classes and we do not want to break up 111 | everything if a refactor is needed 112 | - Dict and built-in types are picklable by default 113 | ``` 114 | 115 | ``` 116 | # Good 117 | Add `use` method to Credit 118 | 119 | Change from namedtuple to class because we need to 120 | setup a new attribute (in_use_amount) with a new value 121 | ``` 122 | 123 | El asunto y el cuerpo del mensaje se separan por una línea en blanco. 124 | Las líneas en blanco adicionales pasan a ser consideradas parte del cuerpo del mensaje. 125 | 126 | Caracteres como `-`, `*` y \` pueden aportar legibilidad. 127 | 128 | ### Evita mensajes genéricos o sin contexto 129 | 130 | ``` 131 | # Bad 132 | Fix this 133 | 134 | Fix stuff 135 | 136 | It should work now 137 | 138 | Change stuff 139 | 140 | Adjust css 141 | ``` 142 | 143 | ### Limita el número de columnas 144 | 145 | [Se recomienda](https://git-scm.com/book/es/v2/Git-en-entornos-distribuidos-Contribuyendo-a-un-Proyecto#r_commit_guidelines) usar un máximo de 50 caracteres para el asunto y 72 para el cuerpo. 146 | 147 | ### Mantén idioma consistente 148 | 149 | Para dueños de proyectos: elijan un idioma y escriban todos los mensajes de commit usando ese idioma. Idealmente debería coincidir con los comentarios del código, la localización por defecto (para proyectos que apliquen), etc. 150 | 151 | Para contribuidores: escriban sus mensajes de commits usando el mismo idioma que los que ya existen en el historial de commits. 152 | 153 | ``` 154 | # Good 155 | ababab Add `use` method to Credit model 156 | efefef Use InventoryBackendPool to retrieve inventory backend 157 | bebebe Fix method name of InventoryBackend child classes 158 | ``` 159 | 160 | ``` 161 | # Good (Spanish example) 162 | ababab Agrega el método `use` a la clase Credit 163 | efefef Usa el InventoryBackendPool para recuperar el backend de stock 164 | bebebe Corrige el nombre de un método de la clase InventoryBackend 165 | ``` 166 | 167 | ``` 168 | # Bad (mixes English and Spanish) 169 | ababab Use InventoryBackendPool to retrieve inventory backend 170 | efefef Add `use` method to Credit model 171 | cdcdcd Listo 172 | ``` 173 | 174 | ### Plantilla 175 | 176 | Esta es una plantilla, [escrita originalmente por Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), que aparece en el [_Libro Pro Git_](https://git-scm.com/book/es/v2/Git-en-entornos-distribuidos-Contribuyendo-a-un-Proyecto). 177 | 178 | ``` 179 | Summarize changes in around 50 characters or less 180 | 181 | More detailed explanatory text, if necessary. Wrap it to about 72 182 | characters or so. In some contexts, the first line is treated as the 183 | subject of the commit and the rest of the text as the body. The 184 | blank line separating the summary from the body is critical (unless 185 | you omit the body entirely); various tools like `log`, `shortlog` 186 | and `rebase` can get confused if you run the two together. 187 | 188 | Explain the problem that this commit is solving. Focus on why you 189 | are making this change as opposed to how (the code explains that). 190 | Are there side effects or other unintuitive consequences of this 191 | change? Here's the place to explain them. 192 | 193 | Further paragraphs come after blank lines. 194 | 195 | - Bullet points are okay, too 196 | 197 | - Typically a hyphen or asterisk is used for the bullet, preceded 198 | by a single space, with blank lines in between, but conventions 199 | vary here 200 | 201 | If you use an issue tracker, put references to them at the bottom, 202 | like this: 203 | 204 | Resolves: #123 205 | See also: #456, #789 206 | ``` 207 | 208 | ## Rebase vs. Merge 209 | 210 | Esta sección es un **TL;DR** del excelente tutorial de Atlassian, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing). 211 | 212 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 213 | 214 | ### Rebase 215 | 216 | **TL;DR:** aplica los commits de tu rama, uno a uno, sobre la rama base, generando un nuevo árbol. 217 | 218 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 219 | 220 | ### Merge 221 | 222 | **TL;DR:** crea un nuevo commit, llamado (adecuadamente) un _commit de merge_, con la diferencia entre las dos ramas. 223 | 224 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 225 | 226 | ### ¿Por qué algunas personas prefieren rebase en lugar de merge? 227 | 228 | Yo particularmente prefiero rebase por sobre merge. Entre otros, los motivos son: 229 | 230 | * Genera una historia más "limpia", sin commits de merge innecesarios 231 | * _Lo que ves es lo que hay_, por ejemplo, en una revisión de código los cambios vendrán de commits específicos y rotulados, evitando cambios ocultos en commits de merge 232 | * Más merges son resueltos por el autor y cada cambio producto de un merge es un commit separado con un mensaje acorde. 233 | * No es una práctica usual indagar y revisar un commit de merge, así que al evitarlos nos aseguramos que los cambios provengan de un commit particular 234 | 235 | ### ¿Cuándo hacer squash? 236 | 237 | "Squashing" es el proceso de tomar una serie de commits y condensarlos en uno solo. 238 | 239 | Es útil en varias situaciones, por ejemplo: 240 | 241 | - Reducir commits muy pequeños o sin contexto (typos, formateos, olvidos) 242 | - Unir cambios separados que cobran más sentido cuando se aplican juntos 243 | - Reescribir commits de trabajo en progreso (WIP) 244 | 245 | ### ¿Cuándo evitar el rebase o squash? 246 | 247 | Evita el uso de rebase y squash en commits que sean públicos o compartidos por varias personas que trabajan en simultáneo. 248 | Rebase y squash reescriben la historia y sobreescriben commits existentes, al hacerlo en commits que pertenecen a ramas compartidas (por ejemplo que fueron publicados en un repositorio remoto) puede causar confusión y pérdida del trabajo de alguien (tanto de manera local como remota) por encontrarnos frente a árboles divergentes y conflictos. 249 | 250 | ## Comandos git útiles 251 | 252 | ### rebase -i 253 | 254 | Úsalo para hacer squash de commits, editar mensajes, reescribir/eliminar/reordenar commits, etc. 255 | 256 | ``` 257 | pick 002a7cc Improve description and update document title 258 | pick 897f66d Add contributing section 259 | pick e9549cf Add a section of Available languages 260 | pick ec003aa Add "What is a commit" section" 261 | pick bbe5361 Add source referencing as a point of help wanted 262 | pick b71115e Add a section explaining the importance of commit messages 263 | pick 669bf2b Add "Good practices" section 264 | pick d8340d7 Add capitalization of first letter practice 265 | pick 925f42b Add a practice to encourage good descriptions 266 | pick be05171 Add a section showing good uses of message body 267 | pick d115bb8 Add generic messages and column limit sections 268 | pick 1693840 Add a section about language consistency 269 | pick 80c5f47 Add commit message template 270 | pick 8827962 Fix triple "m" typo 271 | pick 9b81c72 Add "Rebase vs Merge" section 272 | 273 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 274 | # 275 | # Commands: 276 | # p, pick = use commit 277 | # r, reword = use commit, but edit the commit message 278 | # e, edit = use commit, but stop for amending 279 | # s, squash = use commit, but meld into previous commit 280 | # f, fixup = like "squash", but discard this commit's log message 281 | # x, exec = run command (the rest of the line) using shell 282 | # d, drop = remove commit 283 | # 284 | # These lines can be re-ordered; they are executed from top to bottom. 285 | # 286 | # If you remove a line here THAT COMMIT WILL BE LOST. 287 | # 288 | # However, if you remove everything, the rebase will be aborted. 289 | # 290 | # Note that empty commits are commented out 291 | ``` 292 | 293 | #### fixup 294 | 295 | Úsalo para limpiar commits fácilmente y sin necesidad de un rebase más complejo. 296 | [Este artículo](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) tiene muy buenos ejemplos de cómo y cuándo usarlo. 297 | 298 | ### cherry-pick 299 | 300 | Es útil para aplicar un commit que se hizo en una rama equivocada, sin necesidad de volver a escribirlo. 301 | 302 | Ejemplo: 303 | 304 | ``` 305 | $ git cherry-pick 790ab21 306 | [master 094d820] Fix English grammar in Contributing 307 | Date: Sun Feb 25 23:14:23 2018 -0300 308 | 1 file changed, 1 insertion(+), 1 deletion(-) 309 | ``` 310 | 311 | ### add/checkout/reset [--patch | -p] 312 | 313 | Supongamos que tenemos la siguiente diferencia: 314 | 315 | ```diff 316 | diff --git a/README.md b/README.md 317 | index 7b45277..6b1993c 100644 318 | --- a/README.md 319 | +++ b/README.md 320 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 321 | `` 322 | # Bad (mixes English and Portuguese) 323 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 324 | -efefef Add `use` method to Credit model 325 | cdcdcd Agora vai 326 | `` 327 | 328 | +### Template 329 | + 330 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 331 | + 332 | ## Contributing 333 | 334 | Any kind of help would be appreciated. Example of topics that you can help me with: 335 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 336 | 337 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 338 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 339 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 340 | ``` 341 | 342 | Podemos usar `git add -p` para agregar solo los parches que querramos, sin necesidad de cambiar el código que ya fue escrito. 343 | Es útil también para separar un cambio grande en commits pequeños o hacer reset/checkout de cambios específicos. 344 | 345 | ``` 346 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 347 | Split into 2 hunks. 348 | ``` 349 | 350 | #### hunk 1 351 | 352 | ```diff 353 | @@ -186,7 +186,6 @@ 354 | `` 355 | # Bad (mixes English and Portuguese) 356 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 357 | -efefef Add `use` method to Credit model 358 | cdcdcd Agora vai 359 | `` 360 | 361 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 362 | ``` 363 | 364 | #### hunk 2 365 | 366 | ```diff 367 | @@ -190,6 +189,10 @@ 368 | `` 369 | cdcdcd Agora vai 370 | `` 371 | 372 | +### Template 373 | + 374 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 375 | + 376 | ## Contributing 377 | 378 | Any kind of help would be appreciated. Example of topics that you can help me with: 379 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 380 | 381 | ``` 382 | 383 | #### hunk 3 384 | 385 | ```diff 386 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 387 | 388 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 389 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 390 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 391 | ``` 392 | 393 | ## Otros enlaces interesantes 394 | 395 | - https://whatthecommit.com/ 396 | - https://gitmoji.carloscuesta.me/ 397 | 398 | ## ¿Te gustó? 399 | 400 | [¡Di gracias!](https://saythanks.io/to/RomuloOliveira) 401 | 402 | ## Contribuciones 403 | 404 | Toda ayuda es bienvenida. Ejemplo de temas sobre los que puedes colaborar: 405 | 406 | - Correcciones de gramática y ortografía 407 | - Traducción a otros idiomas 408 | - Mejoras en el código de referencia 409 | - Información incorrecta o incompleta 410 | 411 | ## Fuentes de inspiración, referencias y lecturas adicionales 412 | 413 | - [Cómo escribir un mensaje de commit de git](https://chris.beams.io/posts/git-commit/) 414 | - [Libro Pro Git - Guía de commits](https://git-scm.com/book/es/v2/Git-en-entornos-distribuidos-Contribuyendo-a-un-Proyecto#r_commit_guidelines) 415 | - [Una nota sobre mensajes de commit de git](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 416 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 417 | - [Libro Pro Git - Reescribiendo la Historia](https://git-scm.com/book/es/v2/Herramientas-de-Git-Reescribiendo-la-Historia) 418 | -------------------------------------------------------------------------------- /README_fa-IR.md: -------------------------------------------------------------------------------- 1 | #  راهنمای Commit-Message 2 | 3 | [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | ‫ 6 | راهنمایی برای درک اهمیت Commit-Message و نحوه نوشتن صحیح آن. 7 | 8 | ‫ 9 | این راهنما سعی دارد به شما کمک کند یادبگیرید کامیت چیست، چرا نوشتن Commit-Message مناسب مهم است، 10 | تمرین های خوب و نکاتی که می تواند منجرب به بازنگری و داشتن تاریخچه کامیت بهتری شود 11 | 12 | ## دیگر زبان ها 13 | 14 | - [English](README.md) 15 | - [Português](README_pt-BR.md) 16 | - [Deutsch](README_de-DE.md) 17 | - [Español](README_es-AR.md) 18 | - [Italiano](README_it-IT.md) 19 | - [한국어](README_ko-KR.md) 20 | - [Русский](README_ru-RU.md) 21 | - [简体中文](README_zh-CN.md) 22 | - [日本語](README_ja-JP.md) 23 | - [Українська](README_ua-UA.md) 24 | - [پارسی](README_fa-IR.md) 25 | 26 | ## "Commit" چیست ? 27 | 28 | ‫ 29 | به زبان ساده، یک کامیت اسنپ شات ی از فایل های محلی شما هست که در مخزن محلی نوشته میشود 30 | برخلاف تصور افراد، [گیت تنها تغییرات فایل هارا نگهداری نمی کند بلکه نسخه کاملی از آنها را نگهداری میکند](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences). 31 | و برای فایل هایی که تغییری در آنها داده نشده تنها لینک منطبق با فایل موجود را نگهداری میکند. 32 | 33 | تصویر زیر نحوه ذخیره اطلاعات درطول زمان را نمایش میدهد، در اینجا هر نسخه یک کامیت محسوب میگردد 34 | 35 | ![](https://i.stack.imgur.com/AQ5TG.png) 36 | 37 | ## چرا Commit-Messages اهمیت دارند؟ 38 | 39 | - سرعت بخشیدن و ساده سازی کدریویو 40 | - کمک به فهم تغییرات 41 | - توضیح "دلیل"، که تنها با کد قابل توضیح نیست 42 | - کمک به نگهداری درآینده و فهم چرا و چگونه تغیرات داده شده اند، عیب یابی و اشکال زدایی سریعتر 43 | 44 | برای درک بهتر، چند تمرین و استاندارد در قسمت بعدی توضیح داده خواهد شد 45 | 46 | ## تمرین خوب 47 | 48 | اینها چند تمرین خوب گردآوری شده از تجارب شخصی، اینترنت و سایر راهنماها می باشند، اگه شما با آنها مخالفید یا میتوانید تمرین های بهتر دیگری ارائه دهید میتوانید در توسعه این مخزن مشارکت نمایید 49 | 50 | ### استفاده از فرم دستوری 51 | 52 | ``` 53 | # Good 54 | Use InventoryBackendPool to retrieve inventory backend 55 | ``` 56 | 57 | ``` 58 | # Bad 59 | Used InventoryBackendPool to retrieve inventory backend 60 | ``` 61 | 62 | _اما چرا ما شکل دستوری را استفاده میکنیم?_ 63 | 64 | ‫ 65 | یک Commit-Message درواقع آن چیزی راکه تغییرات انجام میدهد یا تاثیر آن را توضیح میدهد نه چیزی که انجام شده است 66 | 67 | 68 | ### حرف اول با حروف بزرگ 69 | 70 | ``` 71 | # Good 72 | Add `use` method to Credit model 73 | ``` 74 | 75 | ``` 76 | # Bad 77 | add `use` method to Credit model 78 | ``` 79 | 80 | دلیل اینکه اولین حرف باید با حروف بزرگ باشد پیروی از قانون گرامر و استفاده از حروف بزرگ در ابتدای جمله می باشد 81 | 82 | استفاده از این تمرین از شخصی به شخص دیگر، یا از تیمی به تیمی دیگر یا حتی از زبانی به زبان دیگر متفاوت خواهد بود. 83 | استفاده از حروف بزرگ یا کوچک اهمیتی ندارد، نکته مهم پیروی از یک قانون واحد است 84 | 85 | ### سعی در رساندن اینکه تغیر چه کاری انجام میدهد بدون نیاز به مشاهده کد 86 | 87 | ``` 88 | # Good 89 | Add `use` method to Credit model 90 | 91 | ``` 92 | 93 | ``` 94 | # Bad 95 | Add `use` method 96 | ``` 97 | 98 | ``` 99 | # Good 100 | Increase left padding between textbox and layout frame 101 | ``` 102 | 103 | ``` 104 | # Bad 105 | Adjust css 106 | ``` 107 | 108 | در بسیاری از سناریوها مانند کامیت های متعدد، تغییرات مختلف و بازنویسی به بازبینی کننده کمک خواهد کرد که بفهمد کامیت کننده درچه فکری بوده است 109 | 110 | ### استفاده از بدنه Commit-Message برای توضیح "چرا"، "به چه علت"، "چطور" و جزئیات بیشتر 111 | 112 | ``` 113 | # Good 114 | Fix method name of InventoryBackend child classes 115 | 116 | Classes derived from InventoryBackend were not 117 | respecting the base class interface. 118 | 119 | It worked because the cart was calling the backend implementation 120 | incorrectly. 121 | ``` 122 | 123 | ``` 124 | # Good 125 | Serialize and deserialize credits to json in Cart 126 | 127 | Convert the Credit instances to dict for two main reasons: 128 | 129 | - Pickle relies on file path for classes and we do not want to break up 130 | everything if a refactor is needed 131 | - Dict and built-in types are pickleable by default 132 | ``` 133 | 134 | ``` 135 | # Good 136 | Add `use` method to Credit 137 | 138 | Change from namedtuple to class because we need to 139 | setup a new attribute (in_use_amount) with a new value 140 | ``` 141 | 142 | ‫ 143 | موضوع و بدنه پیام کامیت با یک خط خالی جدا می شوند. 144 | خط های خالی اضافی جزئی از بدنه Commit-Message محسوب خواهند شد 145 | 146 | ‫ 147 | کارکتر هایی همچون `-`, `*` و `\` باعث تقویت خوانایی Commit-Message خواهند شد 148 | 149 | ### از متن های کلی یا بی محتوا دوری کنید 150 | 151 | ``` 152 | # Bad 153 | Fix this 154 | 155 | Fix stuff 156 | 157 | It should work now 158 | 159 | Change stuff 160 | 161 | Adjust css 162 | ``` 163 | 164 | ### تعداد کارکتر های مورد استفاده را محدود کنید 165 | 166 | ‫ 167 | [توصیه شده](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) برای موضوع Commit-Message حداکثر 50 کارکتر و برای بدنه آن کداکثر 72 کارکتر استفاده شود. 168 | 169 | ### در استفاده از زبان نوشتن متن ثابت قدم باشید 170 | 171 | ‫ 172 | برای مالک پروژه: انتخاب یک زبان و نوشتن همه Commit-Message ها بوسیله آن، که باید همان زبان مورد استفاده برای کامنت ها و زبان پیش فرض برای پروژه های چند زبانه باشد 173 | 174 | ‫ 175 | برای مشارکت کنندگان: نوشتن Commit-Message با زبان مشابه متن های کامیت قبلی 176 | 177 | ``` 178 | # Good 179 | ababab Add `use` method to Credit model 180 | efefef Use InventoryBackendPool to retrieve inventory backend 181 | bebebe Fix method name of InventoryBackend child classes 182 | ``` 183 | 184 | ``` 185 | # Good (Portuguese example) 186 | ababab Adiciona o método `use` ao model Credit 187 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 188 | bebebe Corrige nome de método na classe InventoryBackend 189 | ``` 190 | 191 | ``` 192 | # Bad (mixes English and Portuguese) 193 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 194 | efefef Add `use` method to Credit model 195 | cdcdcd Agora vai 196 | ``` 197 | 198 | ### قالب 199 | 200 | ‫ 201 | این یک قالب [نوشته شده توسط Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) که در [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) قابل دسترسی می باشد 202 | 203 | ``` 204 | تغیرات را در حدود ۵۰ کاراکتر یا کمتر خلاصه کنید 205 | 206 | متن توضیحات دقیقتر را در ۷۲ کاراکتر بگنجانید، 207 | .اولین خط بعنوان موضوع و مابقی بعنوان بدنه تلقی خواهد شد 208 | 209 | یک خط خالی برای جدا کردن موضوع از بدنه ضرروی خواهد بود 210 | در غیراینصورت ابزارهای مختلف مثل `log`, `shortlog`و `rebase` سردرگم خواهند شد 211 | 212 | مشکلی که کامیت فوق رفع خواهد کرد را توضیح دهید 213 | برخلاف اینکه چطور تغییرات انجام شده برروی چرا تغییرات رو انجام داده اید 214 | فوکوس کنید. 215 | اینکه تغییرات چطور انجام شده در کد مشخص هست 216 | 217 | اینجا مکانی هست که باید توضیح دهید آبا تغیرات تاثیری بر قسمت های مختلف یا عواقب ناخواسته ای خواهند داشت 218 | 219 | 220 | اگر از ابزاری برای مدیریت ایژوهااستفاده می کنید شماره ارجاع مربوط را در انتهای متن قرار بدید 221 | مثال 222 | 223 | Resolves: #123 224 | See also: #456, #789 225 | ``` 226 | اینجا میتوانید متن اصلی را مشاهده نمایید 227 | 228 | ``` 229 | Summarize changes in around 50 characters or less 230 | 231 | More detailed explanatory text, if necessary. Wrap it to about 72 232 | characters or so. In some contexts, the first line is treated as the 233 | subject of the commit and the rest of the text as the body. The 234 | blank line separating the summary from the body is critical (unless 235 | you omit the body entirely); various tools like `log`, `shortlog` 236 | and `rebase` can get confused if you run the two together. 237 | 238 | Explain the problem that this commit is solving. Focus on why you 239 | are making this change as opposed to how (the code explains that). 240 | Are there side effects or other unintuitive consequences of this 241 | change? Here's the place to explain them. 242 | 243 | Further paragraphs come after blank lines. 244 | 245 | - Bullet points are okay, too 246 | 247 | - Typically a hyphen or asterisk is used for the bullet, preceded 248 | by a single space, with blank lines in between, but conventions 249 | vary here 250 | 251 | If you use an issue tracker, put references to them at the bottom, 252 | like this: 253 | 254 | Resolves: #123 255 | See also: #456, #789 256 | ``` 257 | 258 | ## Rebase vs. Merge 259 | 260 | ‫ 261 | این قسمت خلاصه ای از آموزش عالی اطلسین می باشد، ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing). 262 | 263 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 264 | 265 | ### Rebase 266 | 267 | بطور خلاصه قرار دادن کامیت های برنچ شما برروی کامیت های مستر وتولید درخت جدید 268 | 269 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 270 | 271 | ### Merge 272 | 273 | ‫ 274 | بطور خلاصه ایجاد یک کامیت جدید بنام _merge commit_ شامل اختلاف دو برنچ 275 | 276 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 277 | 278 | ### چرا افراد Rebase را به Merge ترجیح میدهند؟ 279 | 280 | من شخصا ریبیس را به مرج ترجیح میدهم به دلایل زیر 281 | 282 | * توسط آن یک تاریخچه کامیت تمیز و بدون کامیت مرج غیرضروری خواهید داشت 283 | * چیزی که شما می بینید چیزی هست که بدست میاورید به این معنی که در بازنگری همه تغییرات در کامیت مربوطه قابل مشاهده هستند وتغییراتی در کامیت مرج مخفی نشده است 284 | * مرجج های بیشتری توسط کامیت کننده برطرف خواهد شد و هر تغییر مرج در کامیتی با متن مناسب خواهد بود 285 | * در حالت عادی کامیت های مرج بررسی نمیشوند بنابراین اجتناب از آنها این اطمینان به ما خواهد داد که همه تغییرات در کامیت مربوطه خواهند بود 286 | 287 | 288 | ### چه وقت از squash استفاده کنیم 289 | 290 | ‫ 291 | "Squashing" پروسه ای می باشد که یک سری ازکامیت ها به یک کامیت تبدیل خواهند شد 292 | و در وضعیت های مختلفی مفید می باشد مانند 293 | 294 | - کاهش تعداد کامیت های بدون محتوا یا کم محتوا مانند اصلاحات تایپی، فرمت کد، چیزهای فراموش شده 295 | - اضافه کردن تغییراتی که درصورت یکی شدن معنی دار خواهند بود 296 | - بازنویسی کامیت های _work in progress_ 297 | 298 | ### چه زمانی از rebase یا squash استفاده نکنیم? 299 | 300 | در زمانی که برروی برنچ های مشترک یا کامیت های عمومی با سایر افراد کار میکنید باید از استفاده از آنها اجتناب کنید 301 | 302 | 303 | این دستورات تاریخچه کامیت ها را بازنویسی همچنین کامیت های موجود رااز بین خواهد برد 304 | در نتیجه انجام آن برروی برنچ های مشترک می تواند باعث ابهام و یا ازدست رفتن تغییرات بدلیل کانفلیک یا انشعابات در درخت کامیت ها گردد 305 | 306 | ## دستورات مفید Git 307 | 308 | ### rebase -i 309 | 310 | از این دستور برای ویرایش کامیت، ریبیس، بازنویسی، حذف یا تغییر ترتیب کامیت ها بطور مثال میتوانید استفاده کنید 311 | 312 | ``` 313 | pick 002a7cc Improve description and update document title 314 | pick 897f66d Add contributing section 315 | pick e9549cf Add a section of Available languages 316 | pick ec003aa Add "What is a commit" section" 317 | pick bbe5361 Add source referencing as a point of help wanted 318 | pick b71115e Add a section explaining the importance of commit messages 319 | pick 669bf2b Add "Good practices" section 320 | pick d8340d7 Add capitalization of first letter practice 321 | pick 925f42b Add a practice to encourage good descriptions 322 | pick be05171 Add a section showing good uses of message body 323 | pick d115bb8 Add generic messages and column limit sections 324 | pick 1693840 Add a section about language consistency 325 | pick 80c5f47 Add commit message template 326 | pick 8827962 Fix triple "m" typo 327 | pick 9b81c72 Add "Rebase vs Merge" section 328 | 329 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 330 | # 331 | # Commands: 332 | # p, pick = use commit 333 | # r, reword = use commit, but edit the commit message 334 | # e, edit = use commit, but stop for amending 335 | # s, squash = use commit, but meld into the previous commit 336 | # f, fixup = like "squash", but discard this commit's log message 337 | # x, exec = run command (the rest of the line) using shell 338 | # d, drop = remove commit 339 | # 340 | # These lines can be re-ordered; they are executed from top to bottom. 341 | # 342 | # If you remove a line here THAT COMMIT WILL BE LOST. 343 | # 344 | # However, if you remove everything, the rebase will be aborted. 345 | # 346 | # Note that empty commits are commented out 347 | ``` 348 | 349 | #### fixup 350 | 351 | ‫ 352 | از این دستور برای پاک سازی آسان بدون نیاز به پیچیدگی های زیاد rebase می توانید استفاده کنید 353 | [این مقاله](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) در بردارنده مثال هایی مفیدی از نحوه و زمان انجام آن می باشد 354 | 355 | 356 | ### cherry-pick 357 | دستور مفیدی برای اضافه کردن کامیتی که در برنچی اشتباهی انجام شده بدون نیاز به کدنویسی مجدد 358 | 359 | Example: 360 | 361 | ``` 362 | $ git cherry-pick 790ab21 363 | [master 094d820] Fix English grammar in Contributing 364 | Date: Sun Feb 25 23:14:23 2018 -0300 365 | 1 file changed, 1 insertion(+), 1 deletion(-) 366 | ``` 367 | 368 | ### add/checkout/reset [--patch | -p] 369 | بطور مثال ما تفاوت زیر را داریم: 370 | 371 | ```diff 372 | diff --git a/README.md b/README.md 373 | index 7b45277..6b1993c 100644 374 | --- a/README.md 375 | +++ b/README.md 376 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 377 | `` 378 | # Bad (mixes English and Portuguese) 379 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 380 | -efefef Add `use` method to Credit model 381 | cdcdcd Agora vai 382 | `` 383 | 384 | +### Template 385 | + 386 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 387 | + 388 | ## Contributing 389 | 390 | Any kind of help would be appreciated. Example of topics that you can help me with: 391 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 392 | 393 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 394 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 395 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 396 | ``` 397 | 398 | ‫ 399 | توسط `git add -p` ما میتوانید تنها پچ هایی که میخواهیم اضافه کنیم، 400 | بدون احتیاج به تغیر کدی که نوشته شده است 401 | همچنین این امکان میسر خواهند بود تغییرات بزرگ به کامیت های کوچکتر شکسته شود یا تغیرات reset/checkout شوند 402 | 403 | ``` 404 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 405 | Split into 2 hunks. 406 | ``` 407 | 408 | #### hunk 1 409 | 410 | ```diff 411 | @@ -186,7 +186,6 @@ 412 | `` 413 | # Bad (mixes English and Portuguese) 414 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 415 | -efefef Add `use` method to Credit model 416 | cdcdcd Agora vai 417 | `` 418 | 419 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 420 | ``` 421 | 422 | #### hunk 2 423 | 424 | ```diff 425 | @@ -190,6 +189,10 @@ 426 | `` 427 | cdcdcd Agora vai 428 | `` 429 | 430 | +### Template 431 | + 432 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 433 | + 434 | ## Contributing 435 | 436 | Any kind of help would be appreciated. Example of topics that you can help me with: 437 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 438 | 439 | ``` 440 | 441 | #### hunk 3 442 | 443 | ```diff 444 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 445 | 446 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 447 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 448 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 449 | ``` 450 | 451 | ## سایت های جالب دیگر 452 | 453 | - https://whatthecommit.com/ 454 | - https://gitmoji.carloscuesta.me/ 455 | 456 | ## مفید بود? 457 | 458 | [تشکر !](https://saythanks.io/to/RomuloOliveira) 459 | 460 | ## مشارکت 461 | از هر نوع کمکی قدردانی خواهد شد بطور مثال در موارد زیر شما میتوانید به بنده کمک کنید 462 | 463 | - گرامر و تصحیح املا 464 | - ترجمه به زبان های دیگر 465 | - تقویت منابع و مراجع 466 | - اصلاعات ناقص و نادرست 467 | 468 | ## منابع الهام گرفته شده و اطلاعات بیشتر 469 | 470 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 471 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 472 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 473 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 474 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 475 | -------------------------------------------------------------------------------- /README_fr-FR.md: -------------------------------------------------------------------------------- 1 | # Guide sur les messages de commit 2 | 3 | [![Dites merci!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Un guide pour comprendre l'importance des messages de commit et comment bien les écrire. 6 | 7 | Cela pourrait vous aider à comprendre ce qu'un commit est, pourquoi c'est important de bien écrire ses messages, les meilleurs techniques et quelques astuces, pour mieux (ré)écrire une bonne "commit history" 8 | 9 | ## Qu'est-ce qu'un "commit" ? 10 | 11 | Dans des termes simples, un commit est une _sauvegarde_ de vos fichiers locaux, écrits dans votre dépôt local. 12 | Contrairement à ce que certaines personnes pensent, [git ne stocke pas seulement la différence entre ces fichiers, il stocke une version complète de tous les fichiers](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences). 13 | Pour les fichiers qui ne changent pas d'un commit à l'autre, git stocke juste un lien vers la version précédente identique qui est déjà stockée. 14 | 15 | L'image ci-dessous montre comment git stocke les fichiers à travers le temps, dans quelle "Version" est un commit. 16 | 17 | ![](https://i.stack.imgur.com/AQ5TG.png) 18 | 19 | ## Pourquoi les messages de commit sont importants ? 20 | 21 | - Pour raccourcir et faciliter les revues de code. 22 | - Pour aider dans la compréhension d'un changement. 23 | - Pour expliquer les "pourquoi", qui ne sauraient être décris en code 24 | - Pour aider les futurs personnes qui vont devoir maintenir le code à comprendre les différents changements, et l'évolution du code. 25 | 26 | Pour maximiser ces résultats, nous pouvons utiliser certaines bonnes pratiques et des standards, décrits dans la prochaine section. 27 | 28 | ## Bons usages 29 | 30 | Il y a quelques bons usages recueillit par l'experience, des articles sur internet, et d'autres guides. Si vous en avez d'autres (ou n'êtes pas d'accord avec certains), soyez libres d'ouvrir une demande de Pull et de contribuer à l'amélioration du guide. 31 | 32 | ### Utilisez l'impératif 33 | 34 | ``` 35 | # Bon 36 | Use InventoryBackendPool to retrieve inventory backend 37 | ``` 38 | 39 | ``` 40 | # Mauvais 41 | Used InventoryBackendPool to retrieve inventory backend 42 | ``` 43 | 44 | _Pourquoi l'impératif ?_ 45 | 46 | Un message de commit décrit ce que le changement **fait**, ces effets, pas ce qui à été fait. 47 | 48 | ### Mettre une majuscule au début de la phrase 49 | 50 | ``` 51 | # Bon 52 | Add `use` method to Credit model 53 | ``` 54 | 55 | ``` 56 | # Mauvais 57 | add `use` method to Credit model 58 | ``` 59 | 60 | On met la première lettre en majuscule pour suivre la règle de grammaire selon laquelle on doit utiliser une majuscule au début d'une phrase. 61 | 62 | Cette pratique peut être ou non appliquée en fonction des personnes, des équipes ou même des languages. Dans tous les cas, l'important est de définir une règle et de s'y tenir. 63 | 64 | ### Essayer de décrire les changements sans avoir à lire le code 65 | 66 | ``` 67 | # Bon 68 | Add `use` method to Credit model 69 | 70 | ``` 71 | 72 | ``` 73 | # Mauvais 74 | Add `use` method 75 | ``` 76 | 77 | ``` 78 | # Bon 79 | Increase left padding between textbox and layout frame 80 | ``` 81 | 82 | ``` 83 | # Mauvais 84 | Adjust css 85 | ``` 86 | 87 | Cela est utile dans de nombreux scenarios (commits multiples, beaucoup changements et refactorisations) pour aider les reviewers à comprendre ce à quoi la personne qui a fait le commit pensait. 88 | 89 | ### Use the message body to explain "why", "for what", "how" and additional details 90 | ### Utiliser le corps du message pour expliquer "pourquoi", pour "quoi", "comment" et autres détails 91 | 92 | ``` 93 | # Bon 94 | Fix method name of InventoryBackend child classes 95 | 96 | Classes derived from InventoryBackend were not 97 | respecting the base class interface. 98 | 99 | It worked because cart was calling the backend implementation 100 | incorrectly. 101 | ``` 102 | 103 | ``` 104 | # Bon 105 | Serialize and deserialize credits to json in Cart 106 | 107 | Convert the Credit instances to dict for two main reasons: 108 | 109 | - Pickle relies on file path for classes and we do not want to break up 110 | everything if a refactor is needed 111 | - Dict and built-in types are picklable by default 112 | ``` 113 | 114 | ``` 115 | # Bon 116 | Add `use` method to Credit 117 | 118 | Change from namedtuple to class because we need to 119 | setup a new attribute (in_use_amount) with a new value 120 | ``` 121 | 122 | L'objet et le corps du message sont séparés par un saut de ligne. 123 | Des sauts de ligne additionels sont considérés comme faisant partie du corps. 124 | Eviter les caractères tels que `-`, `*` et `\` améliore la lisiblité. 125 | 126 | ### Eviter les messages génériques ou sans aucun contexte 127 | 128 | ``` 129 | # Mauvais 130 | Fix this 131 | 132 | Fix stuff 133 | 134 | It should work now 135 | 136 | Change stuff 137 | 138 | Adjust css 139 | ``` 140 | 141 | ### Limiter le nombre de colonnes 142 | 143 | [Il est recommandé](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) d'utiliser un maximum de 50 caractères pour le sujet, et 72 pour le corps. 144 | 145 | ### Garder la cohérence linguistique 146 | 147 | Pour les propriétaires de projet: Choisissez une langue et écrivez tous les messages de validation en utilisant cette langue. Idéalement, il devrait correspondre aux commentaires de code, aux paramètres régionaux de traduction par défaut (pour les projets localisés), etc. 148 | 149 | Pour les contributeurs: Écrivez vos messages de validation en utilisant la même langue que l'historique de validation existant. 150 | 151 | 152 | ``` 153 | # Bon 154 | ababab Add `use` method to Credit model 155 | efefef Use InventoryBackendPool to retrieve inventory backend 156 | bebebe Fix method name of InventoryBackend child classes 157 | ``` 158 | 159 | ``` 160 | # Bon (Exemple Portugais) 161 | ababab Adiciona o método `use` ao model Credit 162 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 163 | bebebe Corrige nome de método na classe InventoryBackend 164 | ``` 165 | 166 | ``` 167 | # Bad (mix Anglais et Portugais) 168 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 169 | efefef Add `use` method to Credit model 170 | cdcdcd Agora vai 171 | ``` 172 | 173 | ### Modèle 174 | 175 | C'est un modèle, [écrit par Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), qui apparait dans le [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 176 | 177 | ``` 178 | Résumer les changements en 50 caractères ou moins. 179 | 180 | Texte explicatif plus détaillé, si nécessaire. Mettez un retour à la ligne à environ 72 caractères. Dans certains contextes, la première ligne est traitée 181 | en tant que sujet du commit et le reste en tant que corps. La ligne 182 | vide séparant le sommaire du corps est critique (sauf si vous omettez complètement le corps); certains outils tels que `log`, `shortlog` et 183 | `rebase` peuvent être confus si vous les fusionnez ensemble. 184 | 185 | Expliquez le problème que ce commit est en train de résoudre. Concentrez-vous sur 186 | les raisons pour lesquelles vous apportez ce changement, par opposition à la 187 | façon dont (le code explique cela). 188 | Est-ce qu'il y at-il des effets secondaires ou d’autres conséquences non intuitives de ce changement? Voici l'endroit pour les expliquer. 189 | 190 | Les autres paragraphes viennent après les lignes vides. 191 | 192 | - Les puces sont ok. 193 | 194 | - Généralement, un tiret ou un astérisque est utilisé pour la puce, précédé d'un espace, avec des lignes vides entre les deux, mais les conventions varient ici. 195 | 196 | Si vous utilisez un outil de suivi des problèmes, 197 | mettez les références à la fin comme ceci: 198 | 199 | Résout: #123 200 | Voir aussi: #456, #789 201 | ``` 202 | 203 | ## Rebase vs. Merge 204 | 205 | Cette section est un **TL;DR** de l'excellent tutoriel d'Atlassian, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing). 206 | 207 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 208 | 209 | ### Rebase 210 | 211 | **TL;DR:** Applique vos commits de branche, un par un, sur la branche principale, générant un nouvel "arbre" 212 | 213 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 214 | 215 | ### Merge 216 | 217 | **TL;DR:** Créé un nouveau commit, appelé un _merge commit_, avec les différences entre ces deux branches. 218 | 219 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 220 | 221 | ### Pourquoi certaines personnes préfères rebase plutôt que merge ? 222 | 223 | Je préfère particulièrement rebase plutôt que merge. Les raisons sont: 224 | 225 | * Cela génère un historique "propre", sans merge commits inutiles. 226 | * Ce que vous voyez est ce que vous obtenez, c’est-à-dire que dans une revue de code, toutes les modifications proviennent d’un commit spécifique, évitant les changements masqués dans les commits de merge. 227 | * Plus de merges sont résolus par la personne qui commit, et chaque modification de merge est dans un commit avec un message propre à celui-ci. 228 | * Il est inhabituel de chercher et d'examiner les commits de merge. Evitez-les donc pour vous assurer que tous les changements ont un commit auquel ils appartiennent. 229 | 230 | ### Quand "squash" 231 | 232 | "Squashing" est le processus consistant à prendre une série de commits et à les condenser en un seul commit. 233 | 234 | C'est utile dans plusieurs situations, e.g.: 235 | 236 | - Réduire le nombre de commit avec peu ou pas de contexte (correction de fautes d'orthographe, formatage, choses oubliées) 237 | - Joindre des modifications distinctes qui ont plus de sens lorsqu'elles sont appliquées ensemble 238 | - Réécrire les commits de _travail en cours_ 239 | 240 | ### Quand éviter rebase ou squash ? 241 | 242 | Il faut éviter rebase et squash dans les commits publiques ou dans les branches partagées où plusieurs personnes travaillent dessus. 243 | Rebase et squash réécrivent l'historique et écrasent les commits existants, le faire sur des commits qui sont dans des branches partagées (i.e., les commits push sur le dépôt distant ou qui viennent d'autres branches) peut entrainer de la confusion, et les gens risquent de perdre leurs changements (autant localement que à distance) car les arbres et les conflicts divergent. 244 | 245 | ## Commandes git pratiques 246 | 247 | ### rebase -i 248 | 249 | Utilisez-la pour squash les commits, modifier les messages, réécrire/supprimer/réorganiser les commits, etc. 250 | 251 | 252 | ``` 253 | pick 002a7cc Improve description and update document title 254 | pick 897f66d Add contributing section 255 | pick e9549cf Add a section of Available languages 256 | pick ec003aa Add "What is a commit" section" 257 | pick bbe5361 Add source referencing as a point of help wanted 258 | pick b71115e Add a section explaining the importance of commit messages 259 | pick 669bf2b Add "Good practices" section 260 | pick d8340d7 Add capitalization of first letter practice 261 | pick 925f42b Add a practice to encourage good descriptions 262 | pick be05171 Add a section showing good uses of message body 263 | pick d115bb8 Add generic messages and column limit sections 264 | pick 1693840 Add a section about language consistency 265 | pick 80c5f47 Add commit message template 266 | pick 8827962 Fix triple "m" typo 267 | pick 9b81c72 Add "Rebase vs Merge" section 268 | 269 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 270 | # 271 | # Commands: 272 | # p, pick = use commit 273 | # r, reword = use commit, but edit the commit message 274 | # e, edit = use commit, but stop for amending 275 | # s, squash = use commit, but meld into previous commit 276 | # f, fixup = like "squash", but discard this commit's log message 277 | # x, exec = run command (the rest of the line) using shell 278 | # d, drop = remove commit 279 | # 280 | # These lines can be re-ordered; they are executed from top to bottom. 281 | # 282 | # If you remove a line here THAT COMMIT WILL BE LOST. 283 | # 284 | # However, if you remove everything, the rebase will be aborted. 285 | # 286 | # Note that empty commits are commented out 287 | ``` 288 | 289 | #### fixup 290 | 291 | Utilisez-la pour nettoyer les commits facilement et sans nécessiter de rebase plus complexe. 292 | [Cet article](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) a de bons exemples de comment et quand le faire. 293 | 294 | ### cherry-pick 295 | 296 | C'est très utile pour appliquer le commit que vous avez fait sur la mauvaise branche, sans qu'il soit nécessaire de le coder à nouveau. 297 | 298 | Exemple: 299 | 300 | ``` 301 | $ git cherry-pick 790ab21 302 | [master 094d820] Fix English grammar in Contributing 303 | Date: Sun Feb 25 23:14:23 2018 -0300 304 | 1 file changed, 1 insertion(+), 1 deletion(-) 305 | ``` 306 | 307 | ### add/checkout/reset [--patch | -p] 308 | 309 | Imaginons que nous avons le diff suivant: 310 | 311 | ```diff 312 | diff --git a/README.md b/README.md 313 | index 7b45277..6b1993c 100644 314 | --- a/README.md 315 | +++ b/README.md 316 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 317 | `` 318 | # Bad (mixes English and Portuguese) 319 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 320 | -efefef Add `use` method to Credit model 321 | cdcdcd Agora vai 322 | `` 323 | 324 | +### Modèle 325 | + 326 | +C'est un modèle, [Ecrit par Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), qui apparait dans [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 327 | + 328 | ## Contribuer 329 | 330 | Toute sorte d'aide est apréciée. Voici quelques exemples de sujets où vous pouvez m'aider. 331 | 332 | @@ -202,3 +205,4 @@ Toute sorte d'aide est apréciée. Voici quelques exemples de sujets où vous pouvez m'aider. 333 | 334 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 335 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 336 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 337 | ``` 338 | 339 | On peut utiliser git add -p pour ajouter uniquement les correctifs que nous voulons, sans qu'il soit nécessaire de modifier le code déjà écrit. 340 | Il est utile de scinder un gros changement en de plus petits commits ou de réinitialiser/extraire des modifications spécifiques. 341 | 342 | ``` 343 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 344 | Split into 2 hunks. 345 | ``` 346 | 347 | #### hunk 1 348 | 349 | ```diff 350 | @@ -186,7 +186,6 @@ 351 | `` 352 | # Bad (mixes English and Portuguese) 353 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 354 | -efefef Add `use` method to Credit model 355 | cdcdcd Agora vai 356 | `` 357 | 358 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 359 | ``` 360 | 361 | #### hunk 2 362 | 363 | ```diff 364 | @@ -190,6 +189,10 @@ 365 | `` 366 | cdcdcd Agora vai 367 | `` 368 | 369 | +### Template 370 | + 371 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 372 | + 373 | ## Contributing 374 | 375 | Any kind of help would be appreciated. Example of topics that you can help me with: 376 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 377 | 378 | ``` 379 | 380 | #### hunk 3 381 | 382 | ```diff 383 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 384 | 385 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 386 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 387 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 388 | ``` 389 | 390 | ## D'autres choses intéréssantes 391 | 392 | - https://whatthecommit.com/ 393 | - https://gitmoji.carloscuesta.me/ 394 | 395 | ## Vous aimez ? 396 | 397 | [Dites merci!](https://saythanks.io/to/RomuloOliveira) 398 | 399 | ## Contribuer 400 | 401 | Toute sorte d'aide est appréciée. Voici quelques exemples de sujets où vous pouvez m'aider : 402 | 403 | - Corrections grammaticales et orthographiques 404 | - Traduction dans d'autres langues 405 | - Meilleures référencement des sources 406 | - Informations incorrectes ou incompletes 407 | 408 | ## Inspirations, sources et lectures complémentaires: 409 | 410 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 411 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 412 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 413 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 414 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 415 | -------------------------------------------------------------------------------- /README_gr-GR.md: -------------------------------------------------------------------------------- 1 | # Οδηγός για τα "Μηνύματα Commit" 2 | 3 | [![Πείτε ευχαριστώ!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Αυτό το κείμενο αποτελεί έναν οδηγό που θα συντελέσει στο να κατανοήσετε την σημασία των μηνυμάτων commit και πώς να τα γράψετε σωστά. 6 | 7 | Ενδεχομένως να σας βοηθήσει να μάθετε τι ακριβώς είναι ένα commit, γιατί θεωρείται σημαντικό το να γράφετε καλά μηνύματα, βέλτιστες πρακτικές και κάποιες συμβουλές για το πώς να προσχεδιάσετε και (ξανά)συντάξετε ένα καλό ιστορικό commit. 8 | 9 | ## Τι είναι ένα "commit"? 10 | 11 | Με απλά λόγια, ένα commit είναι ένα _στιγμιότυπο_ των τοπικών σας αρχείων, γραμμένο στο τοπικό σας απωθητήριο(repository). 12 | Αντίθετα με την γνώμη μερικών, [το git δεν αποθηκεύει μόνο την εκάστοτε διαφορά μεταξύ των αρχείων, αποθηκεύει μία πλήρη έκδοση όλων των αρχείων](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences). 13 | Όσον αφορά τα αρχεία τα οποία δεν άλλαξαν από το ένα commit στο άλλο, το git αποθηκεύει μόνο έναν σύνδεσμο που παραπέμπει στο προηγούμενο, πανομοιότυπο αρχείο που είναι ήδη αποθηκευμένο. 14 | 15 | Η παρακάτω εικόνα αναπαριστά τον τρόπο σύμφωνα με τον οποίο το git αποθηκεύει δεδομένα με την πάροδο του χρόνου, όπου κάθε "Εκδοχή" είναι ένα commit: 16 | 17 | ![](https://i.stack.imgur.com/AQ5TG.png) 18 | 19 | ## Γιατί είναι τα μηνύματα commit σημαντικά? 20 | 21 | - Για να επιταχυνθούν και βελτιστοποιηθούν οι κριτικές κώδικα 22 | - Για να συνδράμουν στην καλύτερη κατανόηση μιας αλλαγής 23 | - Για να εξηγήσουν "τα γιατί (αίτια)" που δεν μπορούν να περιγραφτούν μόνο με την χρήση κώδικα 24 | - Για να βοηθήσουν μελλοντικούς διατηρητές του απωθητηρίου να καταλάβουν γιατί και πώς υλοποιήθηκαν ορισμένες αλλαγές, κάτι που καθιστά την επίλυση προβλημάτων και τον εντοπισμό "bugs" ευκολότερα 25 | 26 | Για να επιτύχουμε αυτά τα αποτελέσματα στον μέγιστο βαθμό, μπορούμε να χρησιμοποιήσουμε ορισμένες καλές πρακτικές και πρότυπα που αναλύονται στο επόμενο τμήμα. 27 | 28 | ## Καλές πρακτικές 29 | 30 | Αυτές είναι μερικές πρακτικές που συνέλεξα από τις εμπειρίες μου, άρθρα στο διαδίκτυο, και άλλους οδηγούς. Εάν έχετε άλλες (ή διαφωνείτε με μερικές) νιώστε ευπρόσδεκτοι να ανοίξετε ένα "Pull Request" και να συνεισφέρετε. 31 | 32 | ### Χρησιμοποιήστε υποτακτική 33 | 34 | ``` 35 | # Καλό 36 | Χρησιμοποιώ InventoryBackendPool για να επανακτήσω inventory backend 37 | ``` 38 | 39 | ``` 40 | # Κακό 41 | Χρησιμοποίησα InventoryBackendPool για να επανακτήσω inventory backend 42 | ``` 43 | 44 | _Αλλά γιατί να χρησιμοποιήσω υποτακτική;_ 45 | 46 | Ένα μήνυμα commit περιγράφει τι η αναφερθείσα αλλαγή **κάνει** στην πραγματικότητα, τις επιδράσεις της, όχι τι συνέβη. 47 | 48 | ### Κάντε το πρώτο γράμμα κεφαλαίο 49 | 50 | ``` 51 | # Καλό 52 | Προσθέσει την `use` μέθοδο στο Credit μοντέλο 53 | ``` 54 | 55 | ``` 56 | # Κακό 57 | προσθέσει την `use` μέθοδο στο Credit μοντέλο 58 | ``` 59 | 60 | Ο λόγος για τον οποίο πρέπει να είναι το πρώτο γράμμα κεφαλαίο είναι για να ακολουθηθεί ο κανόνας της γραμματικής που δηλώνει ότι πρέπει να χρησιμοποιούνται κεφαλαία γράμματα στην αρχή των προτάσεων. 61 | 62 | Η χρήση αυτής της πρακτικής ενδέχεται να ποικίλλει από άτομο σε άτομο, ομάδα σε ομάδα, ή ακόμα από γλώσσα σε γλώσσα. 63 | Με κεφαλαίο πρώτο γράμμα ή όχι, το σημαντικό είναι να παραμείνετε στο να χρησιμοποιείτε ένα μόνο πρότυπο και να το ακολουθήσετε. 64 | 65 | ### Προσπαθήστε να επικοινωνήσετε τι κάνει η εκάστοτε αλλαγή χωρίς να απαιτείται αναδρομή στον πηγαίο κώδικα 66 | 67 | ``` 68 | # Καλό 69 | Προσθέσει την `use` μέθοδο στο Credit μοντέλο 70 | ``` 71 | 72 | ``` 73 | # Κακό 74 | Προσθέσει την `use` μέθοδο 75 | ``` 76 | 77 | ``` 78 | # Καλό 79 | Αυξήσει το αριστερό κενό μεταξύ του textbox και layout frame 80 | ``` 81 | 82 | ``` 83 | # Κακό 84 | Προσαρμόσει το css 85 | ``` 86 | 87 | Είναι λυσιτελές σε πολλές εκδοχές (π.χ. πολλαπλά commits, διάφορες αλλαγές και refactors) το να βοηθήσετε τους κριτικούς κώδικα να καταλάβουν τι σκεφτόταν αυτός που διέπραξε τα commits. 88 | 89 | ### Χρησιμοποιήστε το σώμα κειμένου για να εξηγήσετε "γιατί", "για ποιον σκοπό", "πώς" και επιπρόσθετες λεπτομέρειες 90 | 91 | ``` 92 | # Καλό 93 | Φτιάξει όνομα μεθόδου των παιδιών κλάσεων του InventoryBackend 94 | 95 | Οι κλάσεις που εξήγοντο από το InventoryBackend δεν 96 | σέβοταν το βασικό interface της κλάσης. 97 | 98 | Δούλεψε επειδή το cart καλούσε την υλοποίηση 99 | backend με λάθος τρόπο. 100 | ``` 101 | 102 | ``` 103 | # Καλό 104 | Μετατρέψει τα credits σε σειριακά και αντίστροφα ως json στο Cart 105 | 106 | Μετατροπή των Credit instances σε dict για δύο κύριους λόγους: 107 | 108 | - Το Pickle στηρίζεται στο file path για τις κλάσεις και δεν θέλουμε να 109 | χαλάσουμε τα πάντα εφ' όσον χρειαστεί ένα refactor 110 | - Το dict και οι ενσωματομένοι τύποι είναι δυνατόν να γίνουν 111 | pickled από μόνοι τους 112 | ``` 113 | 114 | ``` 115 | # Καλό 116 | Προσθέσει την `use` μέθοδο στο Credit 117 | 118 | Αλλαγή από namedtuple σε κλάση γιατί χρειαζόμαστε να 119 | εγκατασταστήσουμε ένα καινούργιο attribute (in_use_amount) 120 | με μία νέα τιμή 121 | ``` 122 | 123 | Το θέμα και το σώμα των κειμένων διαχωρίζονται μέσω μίας κενής γραμμής. 124 | Περαιτέρω κενές γραμμές εκλαμβάνονται ως μέρος του σώματος κειμένου. 125 | 126 | Χαρακτήρες όπως `-`, `*` και \` είναι στοιχεία που βελτιώνουν την αναγνωσιμότητα. 127 | 128 | ### Αποφύγετε γενικού ύφους μηνύματα ή μηνύματα χωρίς κάποιο γενικό πλαίσιο 129 | 130 | ``` 131 | # Κακό 132 | Φτιάξει αυτό 133 | 134 | Φτιάξει πράγματα 135 | 136 | Τώρα πρέπει να δουλέψει 137 | 138 | Αλλάξει πράγματα 139 | 140 | Τροποποιήσει το css 141 | ``` 142 | 143 | ### Περιορίστε τον αριθμό των χαρακτήρων 144 | 145 | [Προτείνεται](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) να χρησιμοποιείτε ένα μέγιστο 50 χαρακτήρων για το θέμα και 72 για το σώμα του κειμένου 146 | 147 | ### Διατηρήστε συνοχή στην γλώσσα 148 | 149 | Για τους ιδιοκτήτες project: Διαλέξτε μία γλώσσα και γράψτε όλα τα μηνύματα commit χρησιμοποιώντας αυτήν την γλώσσα. Ιδανικά, θα πρέπει να ταιριάζει με τα σχόλια στον κώδικα, το προκαθορισμένο locale μετάφρασης (για projects τοπικού χαρακτήρα), κτλ. 150 | 151 | Για όσους συνεισφέρουν: Γράψτε τα μηνύματα commit σας χρησιμοποιώντας την ίδια γλώσσα που χρησιμοποιείται στο ήδη υπάρχον ιστορικό commit. 152 | 153 | ``` 154 | # Καλό 155 | ababab Προσθέσει την `use` μέθοδο στο μοντέλο Credit 156 | efefef Χρησιμοποιήσει το InventoryBackendPool για να επανακτήσει το inventory backend 157 | bebebe Διορθώσει το όνομα των μεθόδων των InventoryBackend παιδιών κλάσεων 158 | ``` 159 | 160 | ``` 161 | # Καλό (Παράδειγμα στα Πορτογαλικά) 162 | ababab Adiciona o método `use` ao model Credit 163 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 164 | bebebe Corrige nome de método na classe InventoryBackend 165 | ``` 166 | 167 | ``` 168 | # Κακό (Μπλέκει Αγγλικά και Πορτογαλικά) 169 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 170 | efefef Add `use` method to Credit model 171 | cdcdcd Agora vai 172 | ``` 173 | 174 | ### Πρότυπο 175 | 176 | Αυτό είναι ένα πρότυπο, [που αρχικά έγραψε ο Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), το οποίο εμφανίζεται στο [_Pro Git Βιβλίο_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 177 | 178 | ``` 179 | Αναφέρετε περιληπτικά τις αλλαγές σε περίπου 50 χαρακτήρες ή λιγότερους 180 | 181 | Πιο λεπτομερές επεξηγηματικό κείμενο, εάν κρίνεται απαραίτητο. 182 | Συμπυκνώστε το σε περίπου 72 χαρακτήρες. Εντός κάποιων πλαισίων, 183 | η πρώτη γραμμή αντιμετωπίζεται ως το θέμα του commit και το υπόλοιπο 184 | του κειμένου ως το σώμα του. Η κενή γραμμή που διαχωρίζει την 185 | περίληψη από το σώμα είναι ζωτικής σημασίας (εκτός και αν παραλείψετε 186 | το σώμα εντελώς); ποικίλια εργαλεία όπως τα `log`, `shortlog` και `rebase` 187 | μπορεί να μπερδευτούν αν τρέξετε τα δύο μαζί. 188 | 189 | Εξηγήστε το πρόβλημα που επιλύει αυτό το commit. Εστιάστε στο γιατί 190 | κάνετε αυτήν την αλλαγή αντί στο πώς (ο κώδικας το εξηγεί αυτό). 191 | Υπάρχουν έμμεσες επιδράσεις ή άλλες μη διαισθητικές συνέπειες αυτής 192 | της αλλαγής; Εδώ είναι το μέρος για να τις εξηγήσετε. 193 | 194 | Περαιτέρω παράγραφοι έρχονται μετά από κενές γραμμές. 195 | 196 | - Τα bullet points είναι, και αυτά, εντάξει 197 | 198 | - Συνήθως για το bullet χρησιμοποιείται μία παύλα ή ένας αστερίσκος, 199 | μετά από ένα μόνο κενό, με κενές γραμμές ανάμεσα, αλλά οι συμβάσεις 200 | σχετικά με αυτό το θέμα ποικίλουν. 201 | 202 | Άμα χρησιμοποιείτε έναν issue tracker, τοποθετήστε αναφορές σε αυτούς 203 | στο κάτω μέρος, όπως έτσι: 204 | 205 | Επιλύει: #123 206 | Δείτε επίσης: #456, #789 207 | ``` 208 | 209 | ## Rebase εναντίον Merge 210 | 211 | Αυτό το τμήμα είναι ένα **TL;DR** του εξαιρετικού tutorial του Atlassian, ["Merging εναντίον Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing). 212 | 213 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 214 | 215 | ### Rebase 216 | 217 | **TL;DR:** Εφαρμόζει τα commits στο κλαδί που είστε, ένα ένα, στο κλαδί βάση, παράγοντας ένα καινούργιο δέντρο. 218 | 219 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 220 | 221 | ### Merge 222 | 223 | **TL;DR:** Δημιουργεί ένα νέο commit, το επονομαζόμενο (δικαίως) _merge commit_, με τις διαφορές μεταξύ των δύο κλαδιών. 224 | 225 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 226 | 227 | ### Γιατί μερικοί προτιμούν να κάνουν rebase αντί για merge; 228 | 229 | Εγώ προσωπικά προτιμώ να κάνω rebase αντί για merge. Οι λόγοι περιλαμβάνουν: 230 | 231 | * Παράγει ένα "καθαρό" ιστορικό, χωρίς αχρείαστα merge commits 232 | * _Ότι δείτε είναι ότι παίρνετε_, δηλαδή, σε μια κριτική κώδικα όλες οι αλλαγές προέρχονται από ένα συγκεκριμένο και ονοματιζμένο commit, αποφεύγοντας αλλαγές κρυμμένες μέσα σε merge commits 233 | * Περισσότερα merges επιλύονται από αυτόν που κάνει commit, και κάθε αλλαγή merge είναι σε ένα commit με ένα κατάλληλο μήνυμα 234 | * Είναι ασηνύθιστο να ψάχνεις και να κάνεις κριτική κώδικα σε merge commits, οπότε το να τα αποφεύγεις διασφαλίζει το ότι όλες οι αλλαγές έχουν ένα commit στο οποίο ανήκουν 235 | I particularly prefer to rebase over merge. The reasons include: 236 | 237 | ### Πότε να κάνετε squash 238 | 239 | "Squashing" είναι η διαδικασία του να παίρνεις μια ακολουθία από commits και μετά να τις συμπυκνώνεις σε ένα μόνο commit. 240 | 241 | Είναι χρήσιμο σε πληθώρα περιστάσεων, π.χ: 242 | 243 | - Ελλάτωση commits με λίγο ή καθόλου πλαίσιο (διορθώσεις τυπογραφικών λαθών, formatting, ξεχασμένα πράγματα) 244 | - Σύντμηση διαφορετικών αλλαγών που βγάζουν περισσότερο νόημα όταν εφαρμοστούν μαζί 245 | - Γράψιμο έτη μία φορά _work in progress_ commits 246 | 247 | ### Πότε να αποφύγετε το rebase ή το squash; 248 | 249 | Αποφύγετε τα rebase και squash σε δημόσια commits ή σε κοινόχρηστα κλαδιά όπου δουλεύουν πολλοί άνθρωποι. 250 | Το rebase και το squash ξανά γράφουν το ιστορικό και γράφονται επί των ήδη υπαρχόντων commits, το να τα κάνετε σε commits που είναι σε κοινόχρηστα κλαδιά (δηλαδή, commits που έχετε κάνει push σε remote απωθητήριο ή που προέρχονται από κλαδιά άλλων) μπορεί να προκαλέσει σύγχηση και ενδέχεται άνθρωποι να χάσουν τις αλλαγές τους (και τοπικά και remotely) λόγω των αποκλίνοντων δέντρων και conflicts. 251 | 252 | ## Χρήσιμες εντολές git 253 | 254 | ### rebase -i 255 | 256 | Χρησιμοποιήστε την για να κάνετε squash commits, να επεξεργαστείτε μηνύματα, να ξαναγράψετε/διαγράψετε/αναταξινομήσετε commits, κλπ. 257 | 258 | ``` 259 | pick 002a7cc Improve description and update document title 260 | pick 897f66d Add contributing section 261 | pick e9549cf Add a section of Available languages 262 | pick ec003aa Add "What is a commit" section" 263 | pick bbe5361 Add source referencing as a point of help wanted 264 | pick b71115e Add a section explaining the importance of commit messages 265 | pick 669bf2b Add "Good practices" section 266 | pick d8340d7 Add capitalization of first letter practice 267 | pick 925f42b Add a practice to encourage good descriptions 268 | pick be05171 Add a section showing good uses of message body 269 | pick d115bb8 Add generic messages and column limit sections 270 | pick 1693840 Add a section about language consistency 271 | pick 80c5f47 Add commit message template 272 | pick 8827962 Fix triple "m" typo 273 | pick 9b81c72 Add "Rebase vs Merge" section 274 | 275 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 276 | # 277 | # Commands: 278 | # p, pick = use commit 279 | # r, reword = use commit, but edit the commit message 280 | # e, edit = use commit, but stop for amending 281 | # s, squash = use commit, but meld into the previous commit 282 | # f, fixup = like "squash", but discard this commit's log message 283 | # x, exec = run command (the rest of the line) using shell 284 | # d, drop = remove commit 285 | # 286 | # These lines can be re-ordered; they are executed from top to bottom. 287 | # 288 | # If you remove a line here THAT COMMIT WILL BE LOST. 289 | # 290 | # However, if you remove everything, the rebase will be aborted. 291 | # 292 | # Note that empty commits are commented out 293 | ``` 294 | 295 | #### fixup 296 | 297 | Χρησιμοποιήστε την για να καθαρίσετε commits εύκολα και χωρίς να χρειαστεί ένα πιο πολύπλοκο rebase. 298 | [Αυτό το άρθρο](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) περιέχει πολύ καλά παραδείγματα σχετικλα με το πώς και πότε να το κάνετε. 299 | 300 | ### cherry-pick 301 | 302 | Είναι πολύ χρήσιμη για να εφαρμόσετε το commit που κάνατε στο λάθος κλαδί, χωρίς την ανάγκη να ξαναγράψετε τον κώδικα. 303 | 304 | Παράδειγμα: 305 | ``` 306 | $ git cherry-pick 790ab21 307 | [master 094d820] Φτιάξει ελληνική γραμματική στο "Συνεισφορά" 308 | Date: Sun Feb 25 23:14:23 2018 -0300 309 | 1 file changed, 1 insertion(+), 1 deletion(-) 310 | ``` 311 | 312 | ### add/checkout/reset [--patch | -p] 313 | 314 | Ας υποθέσουμε ότι έχουμε το ακόλουθο diff: 315 | 316 | ```diff 317 | diff --git a/README.md b/README.md 318 | index 7b45277..6b1993c 100644 319 | --- a/README.md 320 | +++ b/README.md 321 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 322 | `` 323 | # Bad (mixes English and Portuguese) 324 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 325 | -efefef Add `use` method to Credit model 326 | cdcdcd Agora vai 327 | `` 328 | 329 | +### Template 330 | + 331 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 332 | + 333 | ## Contributing 334 | 335 | Any kind of help would be appreciated. Example of topics that you can help me with: 336 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 337 | 338 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 339 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 340 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 341 | ``` 342 | 343 | Μπορούμε να χρησιμοποιήσουμε `git add -p` για να προσθέσουμε μόνο τα patches που θέλουμε, χωρίς να χρειάζεται να αλλάξουμε τον κώδικα που έχει ήδη γραφτεί. 344 | Είναι χρήσιμο να διαιρούμε μια μεγάλη αλλαγή σε μικρότερα commits ή να επαναφέρουμε/κάνουμε checkout συγκεκριμένες αλλαγές. 345 | 346 | ``` 347 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 348 | Split into 2 hunks. 349 | ``` 350 | 351 | #### hunk 1 352 | 353 | ```diff 354 | @@ -186,7 +186,6 @@ 355 | `` 356 | # Bad (mixes English and Portuguese) 357 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 358 | -efefef Add `use` method to Credit model 359 | cdcdcd Agora vai 360 | `` 361 | 362 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 363 | ``` 364 | 365 | #### hunk 2 366 | 367 | ```diff 368 | @@ -190,6 +189,10 @@ 369 | `` 370 | cdcdcd Agora vai 371 | `` 372 | 373 | +### Template 374 | + 375 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 376 | + 377 | ## Contributing 378 | 379 | Any kind of help would be appreciated. Example of topics that you can help me with: 380 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 381 | 382 | ``` 383 | 384 | #### hunk 3 385 | 386 | ```diff 387 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 388 | 389 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 390 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 391 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 392 | ``` 393 | 394 | ## Άλλα ενδιαφέροντα πράγματα 395 | 396 | - https://whatthecommit.com/ 397 | - https://gitmoji.carloscuesta.me/ 398 | 399 | ## Σας άρεσε; 400 | 401 | [Πείτε ευχαριστώ!](https://saythanks.io/to/RomuloOliveira) 402 | 403 | ## Συνεισφορά 404 | 405 | Κάθε είδους βοήθειας θα ήταν καλοδεχούμενη. Παράδειγμα από θέματα με τα οποία μπορείτε να με βοηθήσετε: 406 | 407 | - Διορθώσεις στην γραμματική και την ορθογραφία 408 | - Μετάφραση σε άλλες γλώσσες 409 | - Βελτίωση της αναφοράς πηγών 410 | - Λανθασμένη ή ατελής πληροφορία 411 | 412 | ## Εμπνεύσεις, πηγές, και τι να διαβάσετε περαιτέρω 413 | 414 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 415 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 416 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 417 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 418 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 419 | -------------------------------------------------------------------------------- /README_it-IT.md: -------------------------------------------------------------------------------- 1 | # Guida per i messaggi di commit 2 | 3 | [![Ringrazia!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Una guida per capire l'importanza dei messaggi di commit e come scriverli bene. 6 | 7 | Potrebbe aiutarti a capire cos'è un commit, perché è importante scrivere buoni messaggi, buone pratiche e alcuni consigli per pianificare e (ri)scrivere una buona storia per i commit. 8 | 9 | ## Cos'è un "commit"? 10 | 11 | In termini semplici, un commit è una _fotografia_ dei file locali, scritti nel repository locale. 12 | Contrariamente a cosa pensano alcune persone, [git non memorizza solo le differenze tra i file, ma la versione completa di tutti i file](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences). 13 | Per i file che non cambiano tra un commit e l'altro, git memorizza solo un link al file identico precedente che è già memorizzato. 14 | 15 | L'immagine qui sotto mostra come git memorizza i dati nel tempo, nella quale ogni "Version" è un commit: 16 | 17 | ![](https://i.stack.imgur.com/AQ5TG.png) 18 | 19 | ## Perché i messaggi di commit sono importanti?? 20 | 21 | - Per velocizzare e snellire la _code review_ (revisione del codice) 22 | - Per aiutare la comprensione di un cambiamento 23 | - Per spiegare i motivi del cambiamento, che non possono essere spiegati con il solo codice 24 | - Per aiutare i _maintainers_ futuri a capire perché e come i cambiamenti sono stati fatti, rendendo la futura individuazione e risoluzione di problemi più facile 25 | 26 | Per massimizzare questi risultati, possiamo usare alcune buone pratiche e standard descritti nella prossima sezione. 27 | 28 | ## Buone pratiche 29 | 30 | Queste sono alcune (buone) pratiche collezionate dalla mia esperienza, da articoli su internet, e altre guide. Se ne avete altre (o non siete d'accordo su alcune) sentitevi liberi di aprire una Pull Request e contribuire. 31 | 32 | ### Uso della forma imperativa 33 | 34 | ``` 35 | # Corretto 36 | Usa InventoryBackendPool per recuperare il backend dell'inventario 37 | ``` 38 | 39 | ``` 40 | # Errato 41 | Usato InventoryBackendPool per recuperare il backend dell'inventario 42 | ``` 43 | 44 | _Ma perché usare la forma imperativa?_ 45 | 46 | Un messaggio di commit descrive cosa fa il cambiamento (a cui fa riferimento), i suoi effetti,, non cosa è stato fatto. 47 | 48 | ### La prima lettera in maiuscolo 49 | 50 | ``` 51 | # Corretto 52 | Aggiunge il metodo `use` al modello Credit 53 | ``` 54 | 55 | ``` 56 | # Errato 57 | aggiunge il metodo `use` al modello Credit 58 | ``` 59 | 60 | Il motivo per mettere la prima lettera iniziale è per seguire le regole grammaticali che impongono la lettera maiuscola ad inizio di una frase. 61 | 62 | L'uso di questa pratica può variare da persona a persona, gruppo a gruppo, o anche da lingua a lingua. In maiuscolo o no, l'importante è usare un solo standard e seguirlo. 63 | 64 | ### Tenta di comunicare cosa il cambiamento fa senza la necessità di guardare il codice 65 | 66 | ``` 67 | # Corretto 68 | Aggiunge il metodo `use` al modello Credit 69 | 70 | ``` 71 | 72 | ``` 73 | # Errato 74 | Aggiunge il metodo `use` 75 | ``` 76 | 77 | ``` 78 | # Corretto 79 | Incrementa il padding sinistro tra il textbox e 80 | layout frame 81 | ``` 82 | 83 | ``` 84 | # Errato 85 | Sistema il CSS 86 | ``` 87 | 88 | E' utile in tanti scenari (esempio: commit multipli, parecchi cambiamenti e ristrutturazioni) per aiutare i revisori a capire cosa il _committer_ (ovvero chi ha fatto il commit) stava pensando. 89 | 90 | ### Usa il corpo del messaggio per spiegare "perché", "per cosa", "come" e dettagli aggiuntivi 91 | 92 | ``` 93 | # Corretto 94 | Corregge il nome del metodo delle classi figlie 95 | di InventoryBackend 96 | 97 | Classi derivate da InventoryBackend non rispettavano la classe base. 98 | 99 | Funzionava perché il carrello chiamava l'implementazione di backend non 100 | corretta. 101 | ``` 102 | 103 | ``` 104 | # Corretto 105 | Serializza e deserializza i crediti in JSON in 106 | Cart 107 | 108 | Converte le istanze di Credit in dizionario per due motivi: 109 | 110 | - Pickle si basa sul percorso del file per le classi e non vogliamo 111 | rompere tutto se ci sarà una ristrutturazione 112 | - Dizionari e tipi built-in sono pickleable by default 113 | ``` 114 | 115 | ``` 116 | # Corretto 117 | Aggiunge il metodo `use` a Credit 118 | 119 | Cambia da namedtuple a classe perché abbiamo bisogno di preparare un 120 | nuovo attributo (in_use_amount) con un nuovo valore 121 | ``` 122 | 123 | L'oggetto ed il corpo del commit sono separati da una linea vuota. 124 | Linee vuote aggiuntive sono considerate parte del messaggio. 125 | 126 | Caratteri come `-`, `*` e \` sono elementi che aiutano la leggibilità. 127 | 128 | ### Evita messaggi di errore generici o messaggi senza contesto 129 | 130 | ``` 131 | # Errati 132 | Correggi questo 133 | 134 | Corrette delle cose 135 | 136 | Ora dovrebbe funzionare 137 | 138 | Cambia delle cose 139 | 140 | Aggiusta il css 141 | ``` 142 | 143 | ### Limita il numero di colonne 144 | 145 | [E' consigliato](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) usare al massimo 50 caratteri per l'oggetto e 72 per il corpo di ogni commit. 146 | 147 | ### Mantieni la lingua in modo consistente 148 | 149 | Per i proprietari dei progetti: scegli una lingua e scrivi tutti i messaggi di commit in quella lingua. Sarebbe l'ideale se fosse la stessa lingua con cui si scrivono i commenti nel codice, la stessa predefinita per l'applicazione, ecc. 150 | 151 | Per chi collabora: scrivi i messaggi dei tuoi commit rispettando la stessa lingua della history dei commit. 152 | 153 | ``` 154 | # Corretto 155 | ababab Aggiunge il metodo `use` al modello Credit 156 | efefef Usa InventoryBackendPool per recuperare il backend dell'inventario 157 | bebebe Correggi il nome del metodo delle classi figlio di InventoryBackend 158 | ``` 159 | 160 | ``` 161 | # Corretto (esempio in Portuguese) 162 | ababab Adiciona o método `use` ao model Credit 163 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 164 | bebebe Corrige nome de método na classe InventoryBackend 165 | ``` 166 | 167 | ``` 168 | # Errato (mischia English e Portuguese) 169 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 170 | efefef Add `use` method to Credit model 171 | cdcdcd Agora vai 172 | ``` 173 | 174 | ### Modelli 175 | 176 | Questo è un modello, [scritto originariamente da Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), che appare in [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 177 | 178 | ``` 179 | Raccogli i cambiamenti in 50 caratteri o meno 180 | 181 | Una spiegazione più dettagliata se necessario. Vai a capo a circa 72 182 | caratteri. In alcuni contesti, la prima linea è trattata come oggetto 183 | del commit, ed il resto come il corpo. La linea vuota che separa 184 | l'oggetto dal corpo è necessaria (amenoché il corpo non sia vuoto); 185 | vari strumenti come `log`, `shortlog` e `rebase` possono confondersi se 186 | li metti insieme. 187 | 188 | Spiega il problema che questo commit risolve. Focalizzati sul perché 189 | stai facendo questo cambiamento al contrario di come (il codice lo 190 | spiega già di suo). Ci sono side-effects o altre conseguenze non 191 | intuitive a seguito di questo cambiamento? Questo è il posto per 192 | spiegarle. 193 | 194 | Altri paragrafi vengono dopo linee vuote. 195 | 196 | - Elenchi puntati vanno bene 197 | 198 | - Di solito un trattino o un asterisco son usati per il punto, 199 | preceduti da un singolo spazio, con linee vuote nel mezzo, ma qui le 200 | convenzioni variano 201 | 202 | Se hai un sistema di tracciamento delle issues, puoi mettere i 203 | riferimenti alla fine, così: 204 | 205 | Risolve: #123 206 | Vedi anche: #456, #789 207 | ``` 208 | 209 | ## Rebase vs. Merge 210 | 211 | Questa sezione è un **TL;DR** degli eccellenti tutorial di Atlassian, ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing). 212 | 213 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 214 | 215 | ### Rebase 216 | 217 | **TL;DR:** Applica i commit del tuo branch, uno a uno, al branch di base, generato un nuovo albero. 218 | 219 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 220 | 221 | ### Merge 222 | 223 | **TL;DR:** Crea un nuovo commit, chiamato (propriamente) _merge commit_, con le differenze tra i due branches. 224 | 225 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 226 | 227 | ### Perché qualcuno preferisce "rebase" a "merge"? 228 | 229 | Anche io, tra i tanti, preferisco "rebase" a "merge". Le motivazioni sono, tra le altre: 230 | 231 | * Genera una history "pulita", senza _merge commits_ non necessari 232 | * _What you see is what you get_, ovvero in una revisione del codice tutti i cambiamenti arrivano da uno specifico commit, evitando cambiamenti nascosti nei _merge commits_ 233 | * Più merges sono risolti da chi crea il commit, e ogni cambiamento in un merge è un commit con un proprio messaggio 234 | * E' poco comune guardare e revisionare i commit di merge, quindi evitarli del tutto assicura che tutti i cambiamenti sono sotto il commit dove dovrebbero essere 235 | 236 | ### Quando fare lo "squash" 237 | 238 | "Squashing" (o _fare squash_) è il processo di prendere diversi commit e condensarli all'interno di un singolo unico commmit. 239 | 240 | E' utile quando, ad esempio, si vuole: 241 | 242 | - Ridurre i commit con poco o nulla (correzioni di errori ortografici o simili, formattazione, cose dimenticate) 243 | - Unire cambiamenti sperati che hanno più senso applicati insieme 244 | - Riscrivere un commit che era _work in progress_ 245 | 246 | ### Quando evitare "rebase" o "squash"? 247 | 248 | Evita "rebase" e "squash" in commit pubblici, oppure in branch condivisi dove più persone stanno lavorando. 249 | "Rebase" e "squash" riscrivono la storia e sovrascrivono i commit esistenti: fare questo in commit che sono in branch condivisi (ovvero, sincronizzati con repository remoti) può causare confusione, e le persone potrebbero perdere il proprio lavoro (locale o remoto) a causa di alberature divergenti e conflitti. 250 | 251 | ## Comandi git utili 252 | 253 | ### rebase -i 254 | 255 | Usa per fare uno "squash", modificare messaggi, riscrivere/eliminare/riordinare i commit, etc. 256 | 257 | ``` 258 | pick 002a7cc Improve description and update document title 259 | pick 897f66d Add contributing section 260 | pick e9549cf Add a section of Available languages 261 | pick ec003aa Add "What is a commit" section" 262 | pick bbe5361 Add source referencing as a point of help wanted 263 | pick b71115e Add a section explaining the importance of commit messages 264 | pick 669bf2b Add "Good practices" section 265 | pick d8340d7 Add capitalization of first letter practice 266 | pick 925f42b Add a practice to encourage good descriptions 267 | pick be05171 Add a section showing good uses of message body 268 | pick d115bb8 Add generic messages and column limit sections 269 | pick 1693840 Add a section about language consistency 270 | pick 80c5f47 Add commit message template 271 | pick 8827962 Fix triple "m" typo 272 | pick 9b81c72 Add "Rebase vs Merge" section 273 | 274 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 275 | # 276 | # Commands: 277 | # p, pick = use commit 278 | # r, reword = use commit, but edit the commit message 279 | # e, edit = use commit, but stop for amending 280 | # s, squash = use commit, but meld into the previous commit 281 | # f, fixup = like "squash", but discard this commit's log message 282 | # x, exec = run command (the rest of the line) using shell 283 | # d, drop = remove commit 284 | # 285 | # These lines can be re-ordered; they are executed from top to bottom. 286 | # 287 | # If you remove a line here THAT COMMIT WILL BE LOST. 288 | # 289 | # However, if you remove everything, the rebase will be aborted. 290 | # 291 | # Note that empty commits are commented out 292 | ``` 293 | 294 | #### fixup 295 | 296 | Usa per pulire i commit in modo semplice e senza un rebase "complesso". 297 | [Questo articolo](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) ha dei buoni esempi su come e quando fare ciò. 298 | 299 | ### cherry-pick 300 | 301 | E' utile per applicare un commit fatto in un altro branch (anche per errore), senza aver bisogno di riscriverlo. 302 | 303 | Esempio: 304 | 305 | ``` 306 | $ git cherry-pick 790ab21 307 | [master 094d820] Fix English grammar in Contributing 308 | Date: Sun Feb 25 23:14:23 2018 -0300 309 | 1 file changed, 1 insertion(+), 1 deletion(-) 310 | ``` 311 | 312 | ### add/checkout/reset [--patch | -p] 313 | 314 | Facciamo il caso di avere il seguente _diff_: 315 | 316 | ```diff 317 | diff --git a/README.md b/README.md 318 | index 7b45277..6b1993c 100644 319 | --- a/README.md 320 | +++ b/README.md 321 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 322 | `` 323 | # Bad (mixes English and Portuguese) 324 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 325 | -efefef Add `use` method to Credit model 326 | cdcdcd Agora vai 327 | `` 328 | 329 | +### Template 330 | + 331 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 332 | + 333 | ## Contributing 334 | 335 | Any kind of help would be appreciated. Example of topics that you can help me with: 336 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 337 | 338 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 339 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 340 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 341 | ``` 342 | 343 | Possiamo usare `git add -p` per aggiungere solo le patch che vogliamo, senza aver bisogno di cambiare il codice che è già scritto. 344 | E' utile per spezzare grandi cambiamenti in piccoli commit, o per fare il reset/checkout di cambiamenti specifici. 345 | 346 | ``` 347 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 348 | Split into 2 hunks. 349 | ``` 350 | 351 | #### hunk 1 352 | 353 | ```diff 354 | @@ -186,7 +186,6 @@ 355 | `` 356 | # Bad (mixes English and Portuguese) 357 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 358 | -efefef Add `use` method to Credit model 359 | cdcdcd Agora vai 360 | `` 361 | 362 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 363 | ``` 364 | 365 | #### hunk 2 366 | 367 | ```diff 368 | @@ -190,6 +189,10 @@ 369 | `` 370 | cdcdcd Agora vai 371 | `` 372 | 373 | +### Template 374 | + 375 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 376 | + 377 | ## Contributing 378 | 379 | Any kind of help would be appreciated. Example of topics that you can help me with: 380 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 381 | 382 | ``` 383 | 384 | #### hunk 3 385 | 386 | ```diff 387 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 388 | 389 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 390 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 391 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 392 | ``` 393 | 394 | ## Altre cose interessanti 395 | 396 | - https://whatthecommit.com/ 397 | - https://gitmoji.carloscuesta.me/ 398 | 399 | ## Ti piace? 400 | 401 | [Ringrazia!](https://saythanks.io/to/RomuloOliveira) 402 | 403 | ## Contribuire 404 | 405 | Qualsiasi tipo di aiuto è apprezzato. Un esempio di cose per cui potete aiutarmi sono: 406 | 407 | - Correzioni grammaticali e ortografiche 408 | - Traduzione in altre lingue 409 | - Miglioramento nei riferimenti alle sorgenti 410 | - Informazioni parziali o incomplete 411 | 412 | ## Fonti d'ispirazione, sorgenti e altre letture 413 | 414 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 415 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 416 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 417 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 418 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 419 | -------------------------------------------------------------------------------- /README_ja-JP.md: -------------------------------------------------------------------------------- 1 | # コミットメッセージガイド 2 | 3 | [![ありがとう!を言う!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | コミットメッセージの重要性と良いコミットメッセージの書き方を理解するためのガイドです 6 | (訳注: 本日本語訳では、英語でコミットメッセージを書くことを想定します) 7 | 8 | コミットとは何か、良いコミットメッセージを書くことが重要であるのはなぜか、良いコミット履歴を計画し書く(書き直す)ための最良の方法とコツを学ぶのを手助けできるかもしれません。 9 | 10 | ## 「コミット」とは何か? 11 | 12 | 簡単に言うと、コミットとはあなたのローカルリポジトリーに書かれたローカルファイルの _スナップショット_ です。 13 | 人々が考えているのとは異なり、[gitはファイルの差分のみを保持しているのではなく全てのファイルの全てのバージョンのファイルそのものを保持しています](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences)。 14 | 1つのコミットで以前と変更がないファイルについては、gitは既に保持している以前のバージョンの同一ファイルへのリンクを保持します。 15 | 16 | 下図は、gitが経時的にデータをどのように保持しているかを示しています。個々の「version」をコミットだと考えてください。 17 | 18 | ![](https://i.stack.imgur.com/AQ5TG.png) 19 | 20 | ## なぜコミットメッセージは重要なのか? 21 | 22 | - 素早く効率的にコードレビューをするため 23 | - 変更を理解するのを助けるため 24 | - コードのみでは説明できない「なぜ」を説明するため 25 | - 未来のメンテナーが、なぜどのように変更がされたのかを理解し、トラブル解決とデバッグを容易にできるようにするため 26 | 27 | これらの成果を最大化するために、次のセクションで説明する良い事例と標準を使うことができます。 28 | 29 | ## 良い事例 30 | 31 | 私の経験やインターネット上の記事、他のガイドから集めた良い事例があります。 32 | 他に良い事例を知っていたり、賛成できないものがある場合には、気軽にプルリクエストを送って貢献してください。 33 | 34 | ### 命令形を使う 35 | 36 | ``` 37 | # 良い例 38 | Use InventoryBackendPool to retrieve inventory backend 39 | ``` 40 | 41 | ``` 42 | # 悪い例 43 | Used InventoryBackendPool to retrieve inventory backend 44 | ``` 45 | 46 | _しかし、なぜ命令法を使うべきなのでしょうか?_ 47 | 48 | コミットメッセージは、関連付けられる変更が実際に何を*する*のか、どんな効果を持つのかを説明するものであり、何がされたのかを説明するものではありません。 49 | 50 | ### 最初の文字を大文字にする 51 | 52 | ``` 53 | # 良い例 54 | Add `use` method to Credit model 55 | ``` 56 | 57 | ``` 58 | # 悪い例 59 | add `use` method to Credit model 60 | ``` 61 | 62 | 最初の文字を大文字にするのは、文の初めの文字は大文字にするという文法規則に従っています。 63 | 64 | これは人によりチームにより言語により異なります。 65 | 大文字にするにしてもしないにしても、重要なのは1つの標準にこだわり従うことです。 66 | 67 | ### ソースコードを見ることなく変更を伝えられるようにする 68 | 69 | ``` 70 | # 良い例 71 | Add `use` method to Credit model 72 | 73 | ``` 74 | 75 | ``` 76 | # 悪い例 77 | Add `use` method 78 | ``` 79 | 80 | ``` 81 | # 良い例 82 | Increase left padding between textbox and layout frame 83 | ``` 84 | 85 | ``` 86 | # 悪い例 87 | Adjust css 88 | ``` 89 | 90 | このことは、多くのシナリオ(例えば、複数のコミットやいくつかの変更、リファクタリング)で、コミッターが考えていたことをレビュアーが理解するのを助けます。 91 | 92 | ### 「なぜ」「何のために」「どのように」その他の詳細を説明するためにメッセージの本文を使う。 93 | 94 | ``` 95 | # 良い例 96 | Fix method name of InventoryBackend child classes 97 | 98 | Classes derived from InventoryBackend were not 99 | respecting the base class interface. 100 | 101 | It worked because the cart was calling the backend implementation 102 | incorrectly. 103 | ``` 104 | 105 | ``` 106 | # 良い例 107 | Serialize and deserialize credits to json in Cart 108 | 109 | Convert the Credit instances to dict for two main reasons: 110 | 111 | - Pickle relies on file path for classes and we do not want to break up 112 | everything if a refactor is needed 113 | - Dict and built-in types are pickleable by default 114 | ``` 115 | 116 | ``` 117 | # 良い例 118 | Add `use` method to Credit 119 | 120 | Change from namedtuple to class because we need to 121 | setup a new attribute (in_use_amount) with a new value 122 | ``` 123 | 124 | メッセージの件名と本文は空行で区切ります。それ以上の空行はメッセージの本文の一部とみなされます。 125 | 126 | `-`や`*`、\`といった文字は読みやすくするために使えます。 127 | 128 | ### 一般的なメッセージや文脈の分からないメッセージを避ける 129 | 130 | ``` 131 | # 悪い例 132 | Fix this 133 | 134 | Fix stuff 135 | 136 | It should work now 137 | 138 | Change stuff 139 | 140 | Adjust css 141 | ``` 142 | 143 | ### 文字数を制限する 144 | 145 | 件名は50文字、本文は1行につき72文字を上限とするのが[推奨されています](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)。 146 | 147 | ### 言語の一貫性を保つ 148 | 149 | プロジェクトのオーナーへ: 言語を1つ選び、全てのコミットメッセージにその言語を使ってください。 150 | その言語がコード中のコメントやデフォルトの翻訳ロケール(ローカライズされたプロジェクトの場合)などとも一致している方が良いです。 151 | 152 | 貢献者へ: 既に存在するコミット履歴の言語を使ってあなたのコミットメッセージを書いてください。 153 | 154 | ``` 155 | # 良い例 156 | ababab Add `use` method to Credit model 157 | efefef Use InventoryBackendPool to retrieve inventory backend 158 | bebebe Fix method name of InventoryBackend child classes 159 | ``` 160 | 161 | ``` 162 | # 良い例 (ポルトガル語の例) 163 | ababab Adiciona o método `use` ao model Credit 164 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 165 | bebebe Corrige nome de método na classe InventoryBackend 166 | ``` 167 | 168 | ``` 169 | # 悪い例 (英語とポルトガル語が混在している) 170 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 171 | efefef Add `use` method to Credit model 172 | cdcdcd Agora vai 173 | ``` 174 | 175 | ### テンプレート 176 | 177 | これは[元々Tim Popeによって書かれた](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)テンプレートで、[_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project)に収録されています。 178 | 179 | ``` 180 | Summarize changes in around 50 characters or less 181 | 182 | More detailed explanatory text, if necessary. Wrap it to about 72 183 | characters or so. In some contexts, the first line is treated as the 184 | subject of the commit and the rest of the text as the body. The 185 | blank line separating the summary from the body is critical (unless 186 | you omit the body entirely); various tools like `log`, `shortlog` 187 | and `rebase` can get confused if you run the two together. 188 | 189 | Explain the problem that this commit is solving. Focus on why you 190 | are making this change as opposed to how (the code explains that). 191 | Are there side effects or other unintuitive consequences of this 192 | change? Here's the place to explain them. 193 | 194 | Further paragraphs come after blank lines. 195 | 196 | - Bullet points are okay, too 197 | 198 | - Typically a hyphen or asterisk is used for the bullet, preceded 199 | by a single space, with blank lines in between, but conventions 200 | vary here 201 | 202 | If you use an issue tracker, put references to them at the bottom, 203 | like this: 204 | 205 | Resolves: #123 206 | See also: #456, #789 207 | ``` 208 | 209 | ## リベース対マージ 210 | 211 | このセクションは、Atlassianの優れたチュートリアルである["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)をまとめたものです。 212 | 213 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 214 | 215 | ### リベース 216 | 217 | **まとめ**: あなたのブランチのコミットを1つ1つベースのブランチに追加して、新しいツリーを生成します。 218 | 219 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 220 | 221 | ### マージ 222 | 223 | **まとめ**: 適切には _マージコミット_ と呼ばれる、2つのブランチの間の差分である新しいコミットを作成します。 224 | 225 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 226 | 227 | ### なぜマージよりリベースを好む人々がいるのか? 228 | 229 | 私は特にマージよりリベースの方が良いと考えています。理由は以下の通りです。 230 | 231 | * リベースは「クリーン」な履歴を生成し、不必要なマージコミットを生成しない 232 | * 見たままが得られる、つまり、コードレビューで全ての変更が特定のコミットと関連付けられ、マージコミットに変更が隠れるのを防げる 233 | * コミッターによりマージがされるにつれて、それぞれのマージの変更は適切なメッセージを持った1つのコミットにまとまってしまう 234 | * マージコミットを掘り起こしたり、レビューしたりすることは通常やるべきことではない。それを避けるために、全ての変更はそれぞれのコミットを持つようにする 235 | 236 | ### スカッシュすべき時 237 | 238 | 「スカッシュ」とは、一連のコミットを1つのコミットまとめるプロセスです。 239 | 240 | これは、以下の例のような状況では一般的です。 241 | 242 | - 文脈が乏しいまたはないコミットをなくす (誤字を訂正する、フォーマットを整える、忘れていたものを含める) 243 | - 一緒に適用された方がより意味が明確になる分かれた変更をまとめる 244 | - _作業中_ のコミットを書き直す 245 | 246 | ### リベースやスカッシュを避けるべき時は? 247 | 248 | リベースやスカッシュは、公開されたコミットまたは複数の人が作業している共有されたブランチでは避けてください。 249 | リベースやスカッシュは履歴を書き換え、既存のコミットを上書きします。 250 | これを共有されたブランチで行うと混乱をまねき(つまり、コミットはリモートリポジトリーにプッシュされるし、リモートリポジトリーは他の人のブランチから生成される)、ツリーの状態が一貫性を失い競合が発生することで、他の人が自分の変更を(ローカルとリモートの両方で)失うかもしれません。 251 | 252 | ## 有用なgitコマンド 253 | 254 | ### rebase -i 255 | 256 | コミットをスカッシュしたり、メッセージを編集したり、コミットを書き換えたり、削除したり、並べ替えたりするために使います。 257 | 258 | ``` 259 | pick 002a7cc Improve description and update document title 260 | pick 897f66d Add contributing section 261 | pick e9549cf Add a section of Available languages 262 | pick ec003aa Add "What is a commit" section" 263 | pick bbe5361 Add source referencing as a point of help wanted 264 | pick b71115e Add a section explaining the importance of commit messages 265 | pick 669bf2b Add "Good practices" section 266 | pick d8340d7 Add capitalization of first letter practice 267 | pick 925f42b Add a practice to encourage good descriptions 268 | pick be05171 Add a section showing good uses of message body 269 | pick d115bb8 Add generic messages and column limit sections 270 | pick 1693840 Add a section about language consistency 271 | pick 80c5f47 Add commit message template 272 | pick 8827962 Fix triple "m" typo 273 | pick 9b81c72 Add "Rebase vs Merge" section 274 | 275 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 276 | # 277 | # Commands: 278 | # p, pick = use commit 279 | # r, reword = use commit, but edit the commit message 280 | # e, edit = use commit, but stop for amending 281 | # s, squash = use commit, but meld into the previous commit 282 | # f, fixup = like "squash", but discard this commit's log message 283 | # x, exec = run command (the rest of the line) using shell 284 | # d, drop = remove commit 285 | # 286 | # These lines can be re-ordered; they are executed from top to bottom. 287 | # 288 | # If you remove a line here THAT COMMIT WILL BE LOST. 289 | # 290 | # However, if you remove everything, the rebase will be aborted. 291 | # 292 | # Note that empty commits are commented out 293 | ``` 294 | 295 | #### fixup 296 | 297 | もっと複雑なリベースを必要とせず、簡単にコミットを綺麗にするために使います。 298 | [この記事](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html)はどのように、どういう時に使うべきかのとても良い例を示しています。 299 | 300 | ### cherry-pick 301 | 302 | 間違って別のブランチでしてしまったコミットをコードを書き直すことなく適用させるのにとても便利です。 303 | 304 | 例: 305 | 306 | ``` 307 | $ git cherry-pick 790ab21 308 | [master 094d820] Fix English grammar in Contributing 309 | Date: Sun Feb 25 23:14:23 2018 -0300 310 | 1 file changed, 1 insertion(+), 1 deletion(-) 311 | ``` 312 | 313 | ### add/checkout/reset [--patch | -p] 314 | 315 | 以下のような差分があるとします。 316 | 317 | ```diff 318 | diff --git a/README.md b/README.md 319 | index 7b45277..6b1993c 100644 320 | --- a/README.md 321 | +++ b/README.md 322 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 323 | `` 324 | # Bad (mixes English and Portuguese) 325 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 326 | -efefef Add `use` method to Credit model 327 | cdcdcd Agora vai 328 | `` 329 | 330 | +### Template 331 | + 332 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 333 | + 334 | ## Contributing 335 | 336 | Any kind of help would be appreciated. Example of topics that you can help me with: 337 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 338 | 339 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 340 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 341 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 342 | ``` 343 | 344 | `git add -p`を使うことで、必要なパッチのみ追加することができ、既に書かれたコードを変更する必要はありません。 345 | これは大きな変更をより小さなコミットに分割するのに役立ちますし、特定の変更をreset/checkoutするのにも役立ちます。 346 | 347 | ``` 348 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 349 | Split into 2 hunks. 350 | ``` 351 | 352 | #### 部分1 353 | 354 | ```diff 355 | @@ -186,7 +186,6 @@ 356 | `` 357 | # Bad (mixes English and Portuguese) 358 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 359 | -efefef Add `use` method to Credit model 360 | cdcdcd Agora vai 361 | `` 362 | 363 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 364 | ``` 365 | 366 | #### 部分2 367 | 368 | ```diff 369 | @@ -190,6 +189,10 @@ 370 | `` 371 | cdcdcd Agora vai 372 | `` 373 | 374 | +### Template 375 | + 376 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 377 | + 378 | ## Contributing 379 | 380 | Any kind of help would be appreciated. Example of topics that you can help me with: 381 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 382 | 383 | ``` 384 | 385 | #### 部分3 386 | 387 | ```diff 388 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 389 | 390 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 391 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 392 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 393 | ``` 394 | 395 | ## その他の有用なこと 396 | 397 | https://whatthecommit.com/ 398 | 399 | ## 気に入りましたか? 400 | 401 | [ありがとう!を言う](https://saythanks.io/to/RomuloOliveira) 402 | 403 | ## 貢献する 404 | 405 | どんな種類の手助けも歓迎します。例えば以下の事項で手助けしてください。 406 | 407 | - 文法と綴りの訂正 408 | - 他の言語への翻訳 409 | - 他の情報源への参照の改善 410 | - 間違っていたり不完全であったりする情報の訂正 411 | 412 | ## インスピレーションや情報源、次に読むべきもの 413 | 414 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 415 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 416 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 417 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 418 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 419 | -------------------------------------------------------------------------------- /README_ko-KR.md: -------------------------------------------------------------------------------- 1 | # 커밋 메시지 가이드 2 | 3 | [![감사 인사하기!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | 커밋 메시지의 중요성을 이해하고 어떻게 하면 잘 작성할 수 있는지에 대해 설명하는 안내서입니다. 6 | 7 | 커밋 메시지가 무엇이며, 왜 잘 작성하는 것이 중요한지 알아보고 좋은 커밋 히스토리를 유지하고 싶을 때 적용할 수 있는 최고의 접근법과 몇 가지 유용한 팁을 배워봅시다. 8 | 9 | ## "commit" 이 무엇인가요? 10 | 11 | 간단히 말해서, "커밋 (commit)" 은 로컬 저장소에 쓰여지는 로컬 파일들의 단편본입니다. 12 | 일반적으로 사람들이 생각하는 것과는 다르게, [git은 파일의 변경된 내용만을 기록하지 않고 모든 파일의 버전을 모두 기록합니다](https://git-scm.com/book/ko/v2/%EC%8B%9C%EC%9E%91%ED%95%98%EA%B8%B0-Git-%EA%B8%B0%EC%B4%88#_%EC%B0%A8%EC%9D%B4%EA%B0%80_%EC%95%84%EB%8B%88%EB%9D%BC_%EC%8A%A4%EB%83%85%EC%83%B7). 13 | 어떤 한 커밋과 다른 커밋 사이에 변경된 내용이 없다면, git은 이미 동일한 파일에 대해 링크만 생성합니다. 14 | 15 | 아래의 이미지는 시간이 지남에 따라 git이 어떻게 데이터를 저장하는지 보여줍니다. 각 "Version" 은 커밋을 뜻합니다. 16 | 17 | ![](https://i.stack.imgur.com/AQ5TG.png) 18 | 19 | ## 왜 커밋 메시지가 중요한가요? 20 | 21 | - 코드 리뷰 시간을 단축하고 능률적으로 처리하기 위해서 22 | - 변경 사항을 이해하는데 도움을 주기 위해서 23 | - 코드만으론 설명이 어려운 "왜 이렇게 했을까" 를 설명하기 위해서 24 | - 추후 작업할 사람이 왜/어떻게 변경 사항이 만들어졌는지 이해하는데 도움을 주고 문제 해결과 디버깅을 쉽게 만들기 위해서 25 | 26 | 이로부터 얻는 이로운 효과를 극대화 하기 위해, 활용할 수 있는 좋은 습관과 표준을 다음 섹션에서 설명합니다. 27 | 28 | ## 좋은 습관 29 | 30 | 다음 설명할 습관들은 제 개인적인 경험, 인터넷 글, 다른 가이드에서 얻어온 것입니다. 더 추가할 내용(또는 뺄 내용)이 있다면 Pull Request 를 열고 기여해주세요. 31 | 32 | ### 명령조 사용하기 33 | 34 | ``` 35 | # 좋음 36 | InventoryBackendPool을 사용하여 재고 백엔드를 검색합니다 37 | --- 38 | Use InventoryBackendPool to retrieve inventory backend 39 | ``` 40 | 41 | ``` 42 | # 나쁨 43 | InventoryBackendPool을 사용하여 재고 백엔드를 검색했습니다 44 | --- 45 | Used InventoryBackendPool to retrieve inventory backend 46 | ``` 47 | 48 | _근데 왜 명령조를 쓰나요?_ 49 | 50 | 커밋 메시지는 무엇이 변경되었는지가 아니라 실제로 그 변경 사항이 미치는 영향, 즉 변경 사항이 실질적으로 무엇을 하는지 설명합니다. 51 | 52 | ### 첫 번째 문자를 대문자로 시작하기 53 | 54 | ``` 55 | # 좋음 56 | Add `use` method to Credit model 57 | ``` 58 | 59 | ``` 60 | # 나쁨 61 | add `use` method to Credit model 62 | ``` 63 | 64 | 첫 문자를 대문자로 작성해야 하는 이유는 문장의 시작 부분에 대문자를 사용하는 문법 규칙을 따르기 위함입니다. 65 | 66 | 이런 실질적인 규칙의 사용상은 사람, 팀, 언어마다 다를 수 있습니다. 67 | 대문자로 시작하건 아니건, 중요한 것은 하나의 표준을 만들어 계속 따르는 것입니다. 68 | 69 | _역주:_ 한국어는 크게 영향이 없을 듯 합니다. 70 | 71 | ### 소스코드를 보지 않고도 변경 사항이 무엇을 하는지 알 수 있도록 하기 72 | 73 | ``` 74 | # 좋음 75 | Credit 모델에 `use` 메소드 추가 76 | --- 77 | Add `use` method to Credit model 78 | ``` 79 | 80 | ``` 81 | # 나쁨 82 | `use` 메소드 추가 83 | --- 84 | Add `use` method 85 | ``` 86 | 87 | ``` 88 | # 좋음 89 | 텍스트 상자와 레이아웃 프레임 사이 왼쪽 간격 늘림 90 | --- 91 | Increase left padding between textbox and layout frame 92 | ``` 93 | 94 | ``` 95 | # 나쁨 96 | CSS 조정 97 | --- 98 | Adjust css 99 | ``` 100 | 101 | 이는 다양한 상황 (e.g. 다중 커밋, 서로 다른 변경 사항, 리팩토링)에서 코드 리뷰를 진행하는 사람이 커밋 작성자가 무슨 생각을 하고 있었는지 쉽게 이해할 수 있도록 도움을 줄 수 있습니다. 102 | 103 | ### 커밋 메시지 본문으로 "왜", "무엇을 위해", "어떻게" 변경했는지와 상세 내용 추가 설명하기 104 | 105 | ``` 106 | # 좋음 107 | InventoryBackend 자식 클래스의 메소드 이름 수정 108 | 109 | InventoryBackend를 상속받는 클래스가 기반 클래스의 인터페이스를 따르지 않음. 110 | 111 | Cart가 잘못된 방식으로 백엔드 구현을 호출하고 있었기 때문에 문제가 없었음. 112 | --- 113 | Fix method name of InventoryBackend child classes 114 | 115 | Classes derived from InventoryBackend were not 116 | respecting the base class interface. 117 | 118 | It worked because the cart was calling the backend implementation 119 | incorrectly. 120 | ``` 121 | 122 | ``` 123 | # 좋음 124 | Credits을 cart의 json에 직렬화 및 역직렬화합니다 125 | 126 | Credit 객체를 딕셔너리로 전환하는데 두 가지 이유가 있습니다: 127 | 128 | - Pickle이 클래스의 파일 경로에 의존하기 때문에 리팩토링시 로직이 망가질 수 있습니다 129 | - 딕셔너리와 빌트인 타입은 기본적으로 pickle 모듈에 의해 직렬화가 가능합니다 130 | --- 131 | Serialize and deserialize credits to json in Cart 132 | 133 | Convert the Credit instances to dict for two main reasons: 134 | 135 | - Pickle relies on file path for classes and we do not want to break up 136 | everything if a refactor is needed 137 | - Dict and built-in types are pickleable by default 138 | ``` 139 | 140 | ``` 141 | # 좋음 142 | Credit에 `use` 메소드 추가 143 | 144 | 새 속성(in_use_amount)값이 필요하기 때문에 namedtuple에서 클래스로 전환했습니다 145 | --- 146 | Add `use` method to Credit 147 | 148 | Change from namedtuple to class because we need to 149 | setup a new attribute (in_use_amount) with a new value 150 | ``` 151 | 152 | 제목과 메시지 본문은 공백 행 하나로 분리합니다. 153 | 이후 추가되는 공백은 메시지 본문의 일부로 취급합니다. 154 | 155 | `-`, `*`, \` 와 같은 문자를 사용하면 가독성을 향상시킬 수 있습니다. 156 | 157 | ### 맥락 없는 총칭적 메시지 사용 자제하기 158 | 159 | ``` 160 | # 나쁨 161 | 이거 고침 162 | 163 | 뭔가 고침 164 | 165 | 이제 잘 작동할거임 166 | 167 | 뭔가 변경함 168 | 169 | CSS 조정 170 | --- 171 | Fix this 172 | 173 | Fix stuff 174 | 175 | It should work now 176 | 177 | Change stuff 178 | 179 | Adjust css 180 | ``` 181 | 182 | ### 행 글자 수 제한하기 183 | 184 | 제목은 50자, 본문은 72자로 한 줄에 들어갈 수 있는 글자 수를 제한하는 것이 [권장됩니다](https://git-scm.com/book/ko/v2/%EB%B6%84%EC%82%B0-%ED%99%98%EA%B2%BD%EC%97%90%EC%84%9C%EC%9D%98-Git-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-%EA%B8%B0%EC%97%AC%ED%95%98%EA%B8%B0#_commit_guidelines). 185 | 186 | ### 일정한 언어 사용하기 187 | 188 | 프로젝트 소유자인 경우: 언어 하나를 선택해서 모든 커밋을 그 언어만 사용해서 작성합니다. 궁극적으로, 이 규칙은 코드 주석과 기본 언어 파일 (다국어 지원 프로젝트의 경우) 등 모두 일치해야 합니다. 189 | 190 | 기여자의 경우: 이미 커밋 히스토리에서 사용되고 있는 언어를 사용하여 커밋 메시지를 작성합니다. 191 | 192 | ``` 193 | # 좋음 194 | ababab Add `use` method to Credit model 195 | efefef Use InventoryBackendPool to retrieve inventory backend 196 | bebebe Fix method name of InventoryBackend child classes 197 | ``` 198 | 199 | ``` 200 | # 좋음 (한국어 예시) 201 | ababab Credit 모델에 `use` 메소드 추가 202 | efefef InventoryBackendPool을 사용하여 재고 백엔드를 검색합니다 203 | bebebe InventoryBackend 자식 클래스의 메소드 이름 수정 204 | ``` 205 | 206 | ``` 207 | # 나쁨 (영어와 한국어 혼용) 208 | ababab Credit 모델에 `use` 메소드 추가 209 | efefef Use InventoryBackendPool to retrieve inventory backend 210 | cdcdcd 이제 잘 작동할거임 211 | ``` 212 | 213 | ### 템플릿 214 | 215 | 이 템플릿은 [_Pro Git Book_](https://git-scm.com/book/ko/v2/%EB%B6%84%EC%82%B0-%ED%99%98%EA%B2%BD%EC%97%90%EC%84%9C%EC%9D%98-Git-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-%EA%B8%B0%EC%97%AC%ED%95%98%EA%B8%B0)에 나와있는 [Tim Pope의 커밋 메시지](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)를 발췌한 것입니다. 216 | 217 | ``` 218 | 여기에 최대 50자까지 변경 사항에 대해 설명하세요 219 | 220 | 필요하다면 여기에 좀 더 상세하게 설명하세요. 한 줄당 대략 72자까지 맞출 수 있도록 221 | 합니다. 일부 상황에서 첫 줄은 커밋의 제목이 되고, 그 후에 작성되는 텍스트는 본문으로 222 | 취급됩니다. 제목과 본문을 나누는 중간에 삽입되는 공백 행은 매우 중요합니다 (본문을 223 | 완전히 생략하지 않는 이상); `log` 와 `shortlog`, `rebase` 와 같이 다양한 224 | 도구들은 공백에 의존하므로 두 부분을 합쳐버릴 경우 도구가 혼동할 수 있습니다. 225 | 226 | 이 커밋이 해결하고자하는 문제를 설명합니다. 어떻게 했는지보단(코드가 설명할 것이기 때문), 227 | 왜 변경 사항을 적용했는지에 대해 집중합니다. 이 변경 사항으로 인해 생기는 부수 효과가 228 | 있거나 다른 직관적이지 않은 영향이 있을 수 있다면 여기에 설명하세요. 229 | 230 | 앞으로 추가되는 문단은 공백 행 뒤에 옵니다. 231 | 232 | - 필요하다면 강조점을 써도 됩니다 233 | 234 | - 하이픈(-) 또는 별(*)이 주로 강조점으로 사용되고 이후 단일 공백(space)을 삽입합니다 235 | 강조점 사이에는 공백 행을 넣지만 규칙은 언제든지 바꿀 수 있습니다 236 | 237 | 이슈 트래커를 사용한다면 다음과 같이 레퍼런스를 메시지 하단에 삽입하세요: 238 | 239 | 이슈: #123 240 | 같이보기: #456, #789 241 | --- 242 | Explain the problem that this commit is solving. Focus on why you 243 | are making this change as opposed to how (the code explains that). 244 | Are there side effects or other unintuitive consequences of this 245 | change? Here's the place to explain them. 246 | 247 | Further paragraphs come after blank lines. 248 | 249 | - Bullet points are okay, too 250 | 251 | - Typically a hyphen or asterisk is used for the bullet, preceded 252 | by a single space, with blank lines in between, but conventions 253 | vary here 254 | 255 | If you use an issue tracker, put references to them at the bottom, 256 | like this: 257 | 258 | Resolves: #123 259 | See also: #456, #789 260 | ``` 261 | 262 | ## 재정렬 (Rebase) vs. 병합 (Merge) 263 | 264 | 이 섹션은 Atlassian의 멋진 튜토리얼 ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 의 **길어서 안 읽음 요약 좀 (TL;DR)** 버전입니다. 265 | 266 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 267 | 268 | ### 재정렬 (Rebase) 269 | 270 | **한 줄 요약:** 기반 브랜치부터 작업 브랜치의 커밋을 하나씩 차곡차곡 이어붙여 새로운 트리를 만듭니다. 271 | 272 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 273 | 274 | ### 병합 (Merge) 275 | 276 | **한 줄 요약:** 두 브랜치의 변경 사항을 하나로 합쳐 (적절히) _병합된 커밋_ 이라 적힌 하나의 새 커밋을 만듭니다. 277 | 278 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 279 | 280 | ### 왜 사람들은 병합(merge)보다 재정렬(rebase)을 선호하나요? 281 | 282 | 다음과 같은 이유 때문에 저도 병합보단 재정렬을 선호합니다: 283 | 284 | - 불필요한 병합된 커밋 없이 "깔끔한" 기록을 생성합니다 285 | - _보이는 그대로 알 수 있습니다_, 특히, 코드 리뷰에서 커밋의 변경 사항을 병합된 커밋으로 인해 감춰지지 않고 모두 볼 수 있습니다 286 | - 커미터(committer)가 더 직접적으로 병합에 관여하게 되고, 모든 병합 변경 사항이 적절한 커밋 메시지로 대체됩니다 287 | - 병합 커밋을 리뷰하고 파고드는 일은 드묾으로, 병합을 피하면 모든 변경 사항이 각자 적절한 커밋에 연관되도록 할 수 있습니다. 288 | 289 | ### 스쿼시(squash)가 필요할 때 290 | 291 | "스쿼싱 (Squashing)" 은 일련의 커밋을 받아서 하나의 커밋으로 간략화시키는 작업입니다. 292 | 293 | 다음과 같은 상황에 유용할 수 있습니다: 294 | 295 | - 맥락이 없거나 너무 작은 커밋들 줄이기 (오타 교정, 코드 정리, 잊어버린 부분 추가) 296 | - 하나로 합쳤을 때 더 의미가 있는 변경 사항들 297 | - _현재 작업 중 (work in progress)_ 커밋 재작성 298 | 299 | ### 어떨 때 재정렬(rebase), 스쿼시(squash)의 사용을 피해야 하나요? 300 | 301 | 재정렬과 스쿼시 모두 공개된 커밋이나 많은 사람들이 같이 작업하는 공유된 브랜치에선 사용하지 않는 것이 좋습니다. 302 | 재정렬과 스쿼시는 기존 커밋 기록을 다시 작성해서 덮어씌우기 때문에 위에서 언급한 공유된 브랜치(주로, remote로 푸시 된 커밋 또는 다른 브랜치로부터 받은 커밋)에 적용하게 되면 혼란을 빛게되고 분기 트리와 충돌로 인해 다른 사람들이 작업한 변경 사항을 잃을 수도 있습니다(local과 remote 모두). 303 | 304 | ## 유용한 git 커맨드 305 | 306 | ### rebase -i 307 | 308 | 커밋을 스쿼시가 필요할때, 메시지를 변경하거나, 커밋 재작성/삭제/순서 변경이 필요할 때 사용하세요. 309 | 310 | ``` 311 | pick 002a7cc Improve description and update document title 312 | pick 897f66d Add contributing section 313 | pick e9549cf Add a section of Available languages 314 | pick ec003aa Add "What is a commit" section" 315 | pick bbe5361 Add source referencing as a point of help wanted 316 | pick b71115e Add a section explaining the importance of commit messages 317 | pick 669bf2b Add "Good practices" section 318 | pick d8340d7 Add capitalization of first letter practice 319 | pick 925f42b Add a practice to encourage good descriptions 320 | pick be05171 Add a section showing good uses of message body 321 | pick d115bb8 Add generic messages and column limit sections 322 | pick 1693840 Add a section about language consistency 323 | pick 80c5f47 Add commit message template 324 | pick 8827962 Fix triple "m" typo 325 | pick 9b81c72 Add "Rebase vs Merge" section 326 | 327 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 328 | # 329 | # Commands: 330 | # p, pick = use commit 331 | # r, reword = use commit, but edit the commit message 332 | # e, edit = use commit, but stop for amending 333 | # s, squash = use commit, but meld into the previous commit 334 | # f, fixup = like "squash", but discard this commit's log message 335 | # x, exec = run command (the rest of the line) using shell 336 | # d, drop = remove commit 337 | # 338 | # These lines can be re-ordered; they are executed from top to bottom. 339 | # 340 | # If you remove a line here THAT COMMIT WILL BE LOST. 341 | # 342 | # However, if you remove everything, the rebase will be aborted. 343 | # 344 | # Note that empty commits are commented out 345 | ``` 346 | 347 | #### fixup 348 | 349 | 복잡한 재정렬을 할 필요 없이 쉽게 커밋을 정리할 때 사용하세요. [이 글](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html)에서 언제 어떻게 사용해야 하는지 좋은 예시로 설명하고 있습니다. 350 | 351 | ### cherry-pick 352 | 353 | 실수로 엉뚱한 브랜치에 커밋을 했을 때 다시 작업할 필요 없이 해당 커밋을 다른 브랜치에 적용시키고 싶을 때 사용하세요. 354 | 355 | 사용 예시: 356 | 357 | ``` 358 | $ git cherry-pick 790ab21 359 | [master 094d820] Fix English grammar in Contributing 360 | Date: Sun Feb 25 23:14:23 2018 -0300 361 | 1 file changed, 1 insertion(+), 1 deletion(-) 362 | ``` 363 | 364 | ### add/checkout/reset [--patch | -p] 365 | 366 | 다음과 같은 diff가 있다고 가정해 봅시다: 367 | 368 | ```diff 369 | diff --git a/README.md b/README.md 370 | index 7b45277..6b1993c 100644 371 | --- a/README.md 372 | +++ b/README.md 373 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 374 | `` 375 | # Bad (mixes English and Portuguese) 376 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 377 | -efefef Add `use` method to Credit model 378 | cdcdcd Agora vai 379 | `` 380 | 381 | +### Template 382 | + 383 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 384 | + 385 | ## Contributing 386 | 387 | Any kind of help would be appreciated. Example of topics that you can help me with: 388 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 389 | 390 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 391 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 392 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 393 | ``` 394 | 395 | `git add -p` 를 사용하면 코드를 건드리지 않고 원하는 부분만 선택하여 스테이지에 추가할 수 있습니다. 396 | 큰 변경 사항을 작은 커밋으로 쪼개거나 특정 변경 사항을 reset/checkout 할 때 유용하게 사용할 수 있습니다. 397 | 398 | ``` 399 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 400 | Split into 2 hunks. 401 | ``` 402 | 403 | #### hunk 1 404 | 405 | ```diff 406 | @@ -186,7 +186,6 @@ 407 | `` 408 | # Bad (mixes English and Portuguese) 409 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 410 | -efefef Add `use` method to Credit model 411 | cdcdcd Agora vai 412 | `` 413 | 414 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 415 | ``` 416 | 417 | #### hunk 2 418 | 419 | ```diff 420 | @@ -190,6 +189,10 @@ 421 | `` 422 | cdcdcd Agora vai 423 | `` 424 | 425 | +### Template 426 | + 427 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 428 | + 429 | ## Contributing 430 | 431 | Any kind of help would be appreciated. Example of topics that you can help me with: 432 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 433 | 434 | ``` 435 | 436 | #### hunk 3 437 | 438 | ```diff 439 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 440 | 441 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 442 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 443 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 444 | ``` 445 | 446 | ## 다른 흥미로운 것들 447 | 448 | - https://whatthecommit.com/ 449 | - https://gitmoji.carloscuesta.me/ 450 | 451 | ## 맘에 들어요? 452 | 453 | [고마웡!](https://saythanks.io/to/RomuloOliveira) 454 | 455 | ## 기여하기 456 | 457 | 형식에 상관없이 도움을 주시면 감사하겠습니다. 다음과 같은 주제가 있습니다: 458 | 459 | - 문법 또는 철자 교정 460 | - 다른 언어로 번역 461 | - 출처 참조 개선 462 | - 잘못되었거나 완전하지 않은 정보 개선 463 | 464 | ## 영감, 출처, 더 읽어보기 465 | 466 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 467 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 468 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 469 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 470 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 471 | -------------------------------------------------------------------------------- /README_pt-BR.md: -------------------------------------------------------------------------------- 1 | # Guia de mensagens de commit 2 | 3 | [![Diga obrigado!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Um guia para entender a importância das mensagens de commit e como escrevê-las bem. 6 | 7 | Pode te ajudar a aprender o que é um _commit_, entender porque é importante escrever boas mensagens usando boas práticas e conhecer dicas para planejar e (re)escrever o seu histórico de _commits_. 8 | 9 | **Observações:** Apesar da versão em português ter sido escrita antes da versão em inglês, a versão inglês contém alguns textos que estão mais detalhados, assim como melhor referenciamento de fontes. 10 | 11 | ## O que é um "_commit_"? 12 | 13 | Em termos simples, o **_commit_** é uma espécie de _snapshot_ dos seus arquivos locais gravado localmente no seu repositório. Ao contrário do que se pensa, o git *não* armazena apenas as diferenças e sim a cópia completa dos arquivos. 14 | No caso de arquivos que não mudaram de um _commit_ para o outro, é gravada uma referência ao arquivo gerado no último snapshot. 15 | 16 | A imagem abaixo mostra como o git armazena dados ao longo do tempo com uma versão para cada _commit_: 17 | 18 | ![](https://i.stack.imgur.com/AQ5TG.png) 19 | 20 | ## Por que as mensagens são importantes? 21 | 22 | - Facilita e agiliza o _code review_ 23 | - Ajuda no entendimento do que está acontecendo 24 | - Explica os porquês ocultos que não podem ser explicados somente em código 25 | - Facilita a solução de problemas e a depuração garantindo que futuros codificadores entendam por que e como as mudanças foram feitas 26 | 27 | ## Boas práticas 28 | 29 | ### Use o imperativo 30 | 31 | ``` 32 | # Good 33 | Use InventoryBackendPool to retrieve inventory backend 34 | ``` 35 | 36 | ``` 37 | # Bad 38 | Used InventoryBackendPool to retrieve inventory backend 39 | ``` 40 | 41 | Por que!? 42 | 43 | A mensagem de _commit_ diz o que ele **faz**, não o que foi feito. 44 | 45 | ### Primeira letra em maiúsculo 46 | 47 | ``` 48 | # Good 49 | Add `use` method to Credit model 50 | ``` 51 | 52 | ``` 53 | # Bad 54 | add `use` method to Credit model 55 | ``` 56 | 57 | É uma regra bem discutível e a menos importante pra mim. 58 | O motivo de escolher começar com letra maiúscula é simplesmente porque é assim 59 | que se começa uma frase em qualquer texto. 60 | 61 | ### Tente comunicar o que o _commit_ faz sem que seja necessário olhar o conteúdo do _commit_ 62 | 63 | ``` 64 | # Good 65 | Add `use` method to Credit model 66 | 67 | ``` 68 | 69 | ``` 70 | # Bad 71 | Add `use` method 72 | ``` 73 | 74 | ``` 75 | # Good 76 | Increase left padding between textbox and layout frame 77 | ``` 78 | 79 | ``` 80 | # Bad 81 | Adjust css 82 | ``` 83 | 84 | ### Use o corpo da mensagem para explicar "porquê", "para quê", "como" e detalhes adicionais 85 | 86 | ``` 87 | # Good 88 | Fix method name of InventoryBackend child classes 89 | 90 | Classes derived from InventoryBackend were not 91 | respecting the base class interface. 92 | 93 | It worked because cart was calling the backend implementation 94 | incorrectly. 95 | ``` 96 | 97 | ``` 98 | # Good 99 | Serialize and deserialize credits to json in Cart 100 | 101 | Convert the Credit instances to dict for two main reasons: 102 | 103 | - Pickle relies on file path for classes and we do not want to break up 104 | everything if a refactor is needed 105 | - Dict and built-in types are picklable by default 106 | ``` 107 | 108 | ``` 109 | # Good 110 | Add `use` method to Credit 111 | 112 | Change from namedtuple to class because we need to 113 | setup a new attribute (in_use_amount) with a new value 114 | ``` 115 | 116 | O título e o corpo da mensagem são separados por uma linha em branco. 117 | Linhas em branco adicionais são consideradas como parte do corpo. 118 | 119 | Caracteres como `-` e `*` e \` são elementos comuns para melhorar a leitura. 120 | 121 | ### Evite _commits_ com mensagens genéricas ou sem contexto algum 122 | 123 | ``` 124 | # Bad 125 | Fix this 126 | 127 | Fix stuff 128 | 129 | Agora vai 130 | 131 | Change stuff 132 | 133 | Adjust css 134 | ``` 135 | 136 | ### Tente limitar o nº de colunas das mensagens 137 | 138 | [Recomenda-se](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 50 caracteres para o título e por volta de 72 para o corpo. 139 | 140 | ### Mantenha consistência de idioma 141 | 142 | ``` 143 | # Good 144 | ababab Add `use` method to Credit model 145 | efefef Use InventoryBackendPool to retrieve inventory backend 146 | bebebe Fix method name of InventoryBackend child classes 147 | ``` 148 | 149 | ``` 150 | # Good 151 | ababab Adiciona o método `use` ao model Credit 152 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 153 | bebebe Corrige nome de método na classe InventoryBackend 154 | ``` 155 | 156 | ``` 157 | # Bad 158 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 159 | efefef Add `use` method to Credit model 160 | cdcdcd Agora vai 161 | ``` 162 | 163 | ### Exemplo de formato 164 | 165 | ``` 166 | Summarize changes in around 50 characters or less 167 | 168 | More detailed explanatory text, if necessary. Wrap it to about 72 169 | characters or so. In some contexts, the first line is treated as the 170 | subject of the commit and the rest of the text as the body. The 171 | blank line separating the summary from the body is critical (unless 172 | you omit the body entirely); various tools like `log`, `shortlog` 173 | and `rebase` can get confused if you run the two together. 174 | 175 | Explain the problem that this commit is solving. Focus on why you 176 | are making this change as opposed to how (the code explains that). 177 | Are there side effects or other unintuitive consequences of this 178 | change? Here's the place to explain them. 179 | 180 | Further paragraphs come after blank lines. 181 | 182 | - Bullet points are okay, too 183 | 184 | - Typically a hyphen or asterisk is used for the bullet, preceded 185 | by a single space, with blank lines in between, but conventions 186 | vary here 187 | 188 | If you use an issue tracker, put references to them at the bottom, 189 | like this: 190 | 191 | Resolves: #123 192 | See also: #456, #789 193 | ``` 194 | 195 | ## Rebase vs. Merge 196 | 197 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 198 | 199 | ### Rebase 200 | 201 | **TL;DR:** Aplica os _commits_ do seu _branch_, um a um, sobre o _branch_ de base, gerando uma nova árvore 202 | 203 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 204 | 205 | ### Merge 206 | 207 | **TL;DR:** Cria um novo _commit_, chamado de _Merge commit_, com as diferenças entre a sua árvore e a árvore de base 208 | 209 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 210 | 211 | ### Por que algumas pessoas preferem rebase? 212 | 213 | Eu particularmente prefiro o rebase, alguns motivos incluem: 214 | 215 | * Deixa o histórico mais "limpo", sem _commits_ de _merge_ desnecessários espalhados nele 216 | * _What you see is what you get_, i.e., em um code review você está vendo o diff real entre o _master_ e o _branch_ 217 | * Os conflitos mais complexos são resolvidos pelo _commiter_ e ficam dentro de um _commit_, que tem mensagem e propósito 218 | * Ninguém olha o conteúdo dos _commits_ de _merge_ e nisso que mora o perigo 219 | 220 | ### Quando fazer squash 221 | 222 | Squash é o processo de pegar uma série de commits e juntá-los em um commit só. 223 | 224 | É útil em diversas situações, como por exemplo: 225 | 226 | - Muitos _commits_ adicionais sem contexto (correção de _typos_, formatação, coisas esquecidas) 227 | - Mudanças que estão em _commits_ separados que fariam mais sentido parte de um só 228 | - _Commits WIP_ 229 | 230 | ### Quando evitar rebase ou squash? 231 | 232 | Evite _rebase_ e _squash_ em _commits_ públicos ou em _branches_ compartilhadas que outras pessoas possam ter trabalhado. 233 | _Rebase_ e _squash_ reescrevem a história sobrescrevendo commits existentes, fazendo isso em commits que existam em _branches_ compartilhadas (i.e., _commits_ enviados para repositórios remotos ou originados de outras branches) podem causar confusão e as pessoas podem perder suas modificações (tanto locais quanto remotas) por causa de divergências e conflitos. 234 | 235 | ## Comandos úteis 236 | 237 | ### rebase -i 238 | 239 | Usado para fazer _squash_, editar mensagens, editar/apagar/reordenar _commits_, etc. 240 | 241 | ``` 242 | pick 002a7cc Improve description and update document title 243 | pick 897f66d Add contributing section 244 | pick e9549cf Add a section of Available languages 245 | pick ec003aa Add "What is a commit" section" 246 | pick bbe5361 Add source referencing as a point of help wanted 247 | pick b71115e Add a section explaining the importance of commit messages 248 | pick 669bf2b Add "Good practices" section 249 | pick d8340d7 Add capitalization of first letter practice 250 | pick 925f42b Add a practice to encourage good descriptions 251 | pick be05171 Add a section showing good uses of message body 252 | pick d115bb8 Add generic messages and column limit sections 253 | pick 1693840 Add a section about language consistency 254 | pick 80c5f47 Add commit message template 255 | pick 8827962 Fix triple "m" typo 256 | pick 9b81c72 Add "Rebase vs Merge" section 257 | 258 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 259 | # 260 | # Commands: 261 | # p, pick = use commit 262 | # r, reword = use commit, but edit the commit message 263 | # e, edit = use commit, but stop for amending 264 | # s, squash = use commit, but meld into previous commit 265 | # f, fixup = like "squash", but discard this commit's log message 266 | # x, exec = run command (the rest of the line) using shell 267 | # d, drop = remove commit 268 | # 269 | # These lines can be re-ordered; they are executed from top to bottom. 270 | # 271 | # If you remove a line here THAT COMMIT WILL BE LOST. 272 | # 273 | # However, if you remove everything, the rebase will be aborted. 274 | # 275 | # Note that empty commits are commented out 276 | ``` 277 | 278 | #### fixup 279 | 280 | Útil para facilitar a limpeza sem perder tempo/trabalho com um rebase. 281 | [Exemplos](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html). 282 | 283 | ### cherry-pick 284 | 285 | Bastante útil quando você precisa pegar aquele _commit_ que você fez no branch errado sem precisar reescrever novamente. 286 | 287 | Exemplo: 288 | 289 | ``` 290 | $ git cherry-pick 790ab21 291 | [master 094d820] Fix English grammar in Contributing 292 | Date: Sun Feb 25 23:14:23 2018 -0300 293 | 1 file changed, 1 insertion(+), 1 deletion(-) 294 | ``` 295 | 296 | ### add/checkout/reset [--patch | -p] 297 | 298 | Exemplo de diff: 299 | 300 | ```diff 301 | diff --git a/README.md b/README.md 302 | index 7b45277..6b1993c 100644 303 | --- a/README.md 304 | +++ b/README.md 305 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 306 | `` 307 | # Bad (mixes English and Portuguese) 308 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 309 | -efefef Add `use` method to Credit model 310 | cdcdcd Agora vai 311 | `` 312 | 313 | +### Template 314 | + 315 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 316 | + 317 | ## Contributing 318 | 319 | Any kind of help would be appreciated. Example of topics that you can help me with: 320 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 321 | 322 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 323 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 324 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 325 | ``` 326 | 327 | Podemos usar `git add -p` para adicionar apenas os patches que queremos, sem a necessidade de alterar o código que já está escrito. 328 | É útil para dividir uma grande mudança em commits menores ou para fazer reset/checkout de mudanças específicas. 329 | 330 | ``` 331 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 332 | Split into 2 hunks. 333 | ``` 334 | 335 | #### hunk 1 336 | 337 | ```diff 338 | @@ -186,7 +186,6 @@ 339 | `` 340 | # Bad (mixes English and Portuguese) 341 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 342 | -efefef Add `use` method to Credit model 343 | cdcdcd Agora vai 344 | `` 345 | 346 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 347 | ``` 348 | 349 | #### hunk 2 350 | 351 | ```diff 352 | @@ -190,6 +189,10 @@ 353 | `` 354 | cdcdcd Agora vai 355 | `` 356 | 357 | +### Template 358 | + 359 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 360 | + 361 | ## Contributing 362 | 363 | Any kind of help would be appreciated. Example of topics that you can help me with: 364 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 365 | 366 | ``` 367 | 368 | #### hunk 3 369 | 370 | ```diff 371 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 372 | 373 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 374 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 375 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 376 | ``` 377 | 378 | ## Links interessantes 379 | 380 | - https://whatthecommit.com/ 381 | - https://gitmoji.carloscuesta.me/ 382 | 383 | ## Gostou? 384 | 385 | [Mandar um obrigado!](https://saythanks.io/to/RomuloOliveira) 386 | 387 | ## Contribuindo 388 | 389 | Todo tipo de ajuda é bem-vinda. Exemplos de tópicos em que você pode contribuir: 390 | 391 | - Correcões gramaticais e ortográficas 392 | - Tradução para novas línguas 393 | - Melhoras nas referências e fontes 394 | 395 | ## Inspirações, fontes e leitura adicional 396 | 397 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 398 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 399 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 400 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 401 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 402 | -------------------------------------------------------------------------------- /README_ru-RU.md: -------------------------------------------------------------------------------- 1 | # Руководство по написанию коммитов 2 | 3 | [![Скажи спасибо!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Это руководство поможет понять, почему важно писать хорошие сообщения коммитов и как это делать. 6 | 7 | Также это руководство может помочь прояснить, что такое коммит, почему важно писать хорошие сообщения, узнать лучшие практики и советы по созданию и (пере)написанию истории коммитов. 8 | 9 | ## Что такое "коммит"? 10 | 11 | Простыми словами, коммит — это _снимок_ ваших локальных файлов, записанный в локальный репозиторий. 12 | Вопреки распространённому мнению, [git хранит не только изменения между файлами, но и в целом полную версию всех файлов](https://git-scm.com/book/ru/v2/%D0%92%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5-%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D1%8B-Git). 13 | Для файлов, которые не менялись от одного коммита к другому, git хранит только ссылку на предыдущий идентичный файл, который уже был сохранен. 14 | 15 | На изображении ниже показано, как git хранит данные с течением времени. Каждая "версия" является коммитом: 16 | 17 | ![](https://i.stack.imgur.com/AQ5TG.png) 18 | 19 | ## Почему сообщения коммитов важны? 20 | 21 | - Чтобы ускорить и упростить проверку кода 22 | - Чтобы помочь в понимании изменений 23 | - Чтобы объяснить вопросы, которые не могут быть описаны только кодом 24 | - Чтобы помочь будущим разработчикам разобраться, почему и как были сделаны изменения, облегчив поиск и устранение ошибок 25 | 26 | Чтобы добиться максимального результата, мы можем использовать некоторые полезные практики и стандарты, описанные в следующем разделе. 27 | 28 | ## Полезные практики 29 | 30 | Это некоторые практики, собранные из моего опыта, статей и других руководств. Если у вас есть предложение (или вы не согласны с некоторым) не стесняйтесь открыть пулреквест и внести свой вклад. 31 | 32 | ### Используйте повелительное наклонение 33 | 34 | ``` 35 | # Хорошо 36 | Use InventoryBackendPool to retrieve inventory backend 37 | ``` 38 | 39 | ``` 40 | # Плохо 41 | Used InventoryBackendPool to retrieve inventory backend 42 | ``` 43 | 44 | _Но зачем использовать повелительное наклонение?_ 45 | 46 | Сообщение коммита описывает, что конкретно **делают** зафиксированные изменения, его конечный результат, а не что было сделано. 47 | 48 | ### Начинайте сообщение коммита с заглавной буквы 49 | 50 | ``` 51 | # Хорошо 52 | Add `use` method to Credit model 53 | ``` 54 | 55 | ``` 56 | # Плохо 57 | add `use` method to Credit model 58 | ``` 59 | 60 | Смысл этой рекомендации простой: в соответствии с правилами грамматики первое слово предложения начинается с заглавной буквы. 61 | 62 | Использование этой практики может варьироваться от человека к человеку, от команды к команде или даже от языка к языку. 63 | Заглавная или нет, важно придерживаться единого стандарта и следовать ему. 64 | 65 | ### Старайтесь описывать изменения так, чтобы указывать на исходный код 66 | 67 | ``` 68 | # Хорошо 69 | Add `use` method to Credit model 70 | 71 | ``` 72 | 73 | ``` 74 | # Плохо 75 | Add `use` method 76 | ``` 77 | 78 | ``` 79 | # Хорошо 80 | Increase left padding between textbox and layout frame 81 | ``` 82 | 83 | ``` 84 | # Плохо 85 | Adjust css 86 | ``` 87 | 88 | Это полезно во многих случаях (пр. несколько коммитов, различные изменения и рефакторинг), чтобы помочь проверяющим понять о чём думал автор коммита. 89 | 90 | ### Используйте тело сообщения для объяснения "почему", "для чего", "как" и дополнительные детали 91 | 92 | ``` 93 | # Хорошо 94 | Fix method name of InventoryBackend child classes 95 | 96 | Classes derived from InventoryBackend were not 97 | respecting the base class interface. 98 | 99 | It worked because the cart was calling the backend implementation 100 | incorrectly. 101 | ``` 102 | 103 | ``` 104 | # Хорошо 105 | Serialize and deserialize credits to json in Cart 106 | 107 | Convert the Credit instances to dict for two main reasons: 108 | 109 | - Pickle relies on file path for classes and we do not want to break up 110 | everything if a refactor is needed 111 | - Dict and built-in types are pickleable by default 112 | ``` 113 | 114 | ``` 115 | # Хорошо 116 | Add `use` method to Credit 117 | 118 | Change from namedtuple to class because we need to 119 | setup a new attribute (in_use_amount) with a new value 120 | ``` 121 | 122 | Тема и описание сообщения разделены пустой строкой. 123 | 124 | Дополнительные пустые строки считаются частью описания. 125 | 126 | Такие символы как `-`, `*` и ` улучшают общую читаемость. 127 | 128 | ### Избегайте общих сообщений или сообщений без какого-либо контекста 129 | 130 | ``` 131 | # Плохо 132 | Fix this 133 | 134 | Fix stuff 135 | 136 | It should work now 137 | 138 | Change stuff 139 | 140 | Adjust css 141 | ``` 142 | 143 | ### Ограничьте длину строк 144 | 145 | [Рекомендуется](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) использовать максимум 50 символов для темы и 72 символа для описания. 146 | 147 | ### Сохраняйте согласованность языка 148 | 149 | Для владельцев проектов: Выберите язык и пишите все сообщения коммитов используя этот язык. В идеале, он должен совпадать с комментариями в коде, стандартным переводом (для переведенных проектов), и т.д. 150 | 151 | Для участников проекта: Пишите сообщения коммитов на том языке, который используется в истории коммитов. 152 | 153 | ``` 154 | # Хорошо 155 | ababab Add `use` method to Credit model 156 | efefef Use InventoryBackendPool to retrieve inventory backend 157 | bebebe Fix method name of InventoryBackend child classes 158 | ``` 159 | 160 | ``` 161 | # Хорошо (Португальский пример) 162 | ababab Adiciona o método `use` ao model Credit 163 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 164 | bebebe Corrige nome de método na classe InventoryBackend 165 | ``` 166 | 167 | ``` 168 | # Плохо (смесь Английского и Португальского) 169 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 170 | efefef Add `use` method to Credit model 171 | cdcdcd Agora vai 172 | ``` 173 | 174 | ### Шаблон 175 | 176 | Этот шаблон, [который изначально описан Тимом Поупом (Tim Pope)](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), также упоминается в [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 177 | 178 | ``` 179 | Summarize changes in around 50 characters or less 180 | 181 | More detailed explanatory text, if necessary. Wrap it to about 72 182 | characters or so. In some contexts, the first line is treated as the 183 | subject of the commit and the rest of the text as the body. The 184 | blank line separating the summary from the body is critical (unless 185 | you omit the body entirely); various tools like `log`, `shortlog` 186 | and `rebase` can get confused if you run the two together. 187 | 188 | Explain the problem that this commit is solving. Focus on why you 189 | are making this change as opposed to how (the code explains that). 190 | Are there side effects or other unintuitive consequences of this 191 | change? Here's the place to explain them. 192 | 193 | Further paragraphs come after blank lines. 194 | 195 | - Bullet points are okay, too 196 | 197 | - Typically a hyphen or asterisk is used for the bullet, preceded 198 | by a single space, with blank lines in between, but conventions 199 | vary here 200 | 201 | If you use an issue tracker, put references to them at the bottom, 202 | like this: 203 | 204 | Resolves: #123 205 | See also: #456, #789 206 | ``` 207 | 208 | ## Перебазировка vs. Слияние 209 | 210 | Этот раздел является кратким пересказом превосходного руководства ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) от Atlassian. 211 | 212 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 213 | 214 | ### Перебазирование 215 | 216 | **Кратко:** Применяет ваши коммиты в ветке, один за другим, к базовой ветки (например, master), генерируя новое дерево. 217 | 218 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 219 | 220 | ### Слияние 221 | 222 | **Кратко:** Создаёт новый коммит, называемый (соответственно) _коммит слияния_ (_merge commit_), с различиями между двумя ветками. 223 | 224 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 225 | 226 | ### Почему некоторые люди предпочитают перебазирование вместо слияния? 227 | 228 | Я, в частности, предпочитаю перебазирование вместо слияния. По следующим причинам: 229 | 230 | * Это создает "чистую" историю, без ненужных коммитов-слияний 231 | * _Что видишь, то и имеешь,_, т.е. при ревью кода все изменения идут от определенного коммита, без скрытых изменений в коммитах при слиянии 232 | * Больше слияний решаются автором коммита, поэтому каждое слитое изменение находится в коммите с соответствующим сообщением 233 | * Обычно не смотрят коммиты-слияния, так что таким образом все изменения зафиксированы в коммите, к которому они непосредственно относятся 234 | 235 | ### Когда нужно делать объединение коммитов? 236 | 237 | Объединение (Squashing) — это процесс объединения множества коммитов в один-единственный коммит. 238 | 239 | Это может пригодиться в ряде ситуаций, например: 240 | 241 | - Уменьшение количества коммитов с небольшим контекстом или без контекста (исправление опечаток, форматирование, дополнения) 242 | - Объединение независимых изменений, которые лучше всего применять вместе 243 | - Переписывание коммитов в стадии _WIP_ (черновика) 244 | 245 | ### Когда избегать перебазирования или сжатия? 246 | 247 | Избегайте этого в публичных коммитах или в общих ветках, в которых работают несколько человек. 248 | Перебазирование и слияние также перезаписывает историю коммитов и существующие коммиты, делая это с коммитами, которые находятся в разных ветках (например, коммиты, отправленные в удаленный репозиторий или коммиты из других веток) могут вызвать путаницу и поэтому можно потерять изменения (как локальные, так и удаленные) из-за различающегося дерева и конфликтов. 249 | 250 | ## Полезные команды git 251 | 252 | ### rebase -i 253 | 254 | Используйте их, чтобы объединить коммиты, изменить сообщения, переписать/удалить/изменить порядок коммитов и т.д. 255 | 256 | ``` 257 | pick 002a7cc Improve description and update document title 258 | pick 897f66d Add contributing section 259 | pick e9549cf Add a section of Available languages 260 | pick ec003aa Add "What is a commit" section" 261 | pick bbe5361 Add source referencing as a point of help wanted 262 | pick b71115e Add a section explaining the importance of commit messages 263 | pick 669bf2b Add "Good practices" section 264 | pick d8340d7 Add capitalization of first letter practice 265 | pick 925f42b Add a practice to encourage good descriptions 266 | pick be05171 Add a section showing good uses of message body 267 | pick d115bb8 Add generic messages and column limit sections 268 | pick 1693840 Add a section about language consistency 269 | pick 80c5f47 Add commit message template 270 | pick 8827962 Fix triple "m" typo 271 | pick 9b81c72 Add "Rebase vs Merge" section 272 | 273 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 274 | # 275 | # Commands: 276 | # p, pick = use commit 277 | # r, reword = use commit, but edit the commit message 278 | # e, edit = use commit, but stop for amending 279 | # s, squash = use commit, but meld into the previous commit 280 | # f, fixup = like "squash", but discard this commit's log message 281 | # x, exec = run command (the rest of the line) using shell 282 | # d, drop = remove commit 283 | # 284 | # These lines can be re-ordered; they are executed from top to bottom. 285 | # 286 | # If you remove a line here THAT COMMIT WILL BE LOST. 287 | # 288 | # However, if you remove everything, the rebase will be aborted. 289 | # 290 | # Note that empty commits are commented out 291 | ``` 292 | 293 | #### fixup 294 | 295 | Используйте эту команду, чтобы привести в порядок коммиты, не прибегая к перебазированию. 296 | В [этой статье](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) есть хорошие примеры того, как и когда это делать. 297 | 298 | 299 | ### cherry-pick 300 | 301 | Эта команда может быть очень полезной для применения коммита, который был сделан в неверной ветке, чтобы не писать код заново. 302 | 303 | Пример: 304 | 305 | ``` 306 | $ git cherry-pick 790ab21 307 | [master 094d820] Fix English grammar in Contributing 308 | Date: Sun Feb 25 23:14:23 2018 -0300 309 | 1 file changed, 1 insertion(+), 1 deletion(-) 310 | ``` 311 | 312 | ### add/checkout/reset [--patch | -p] 313 | 314 | Давайте представим, что у нас есть следующий список различий: 315 | 316 | ```diff 317 | diff --git a/README.md b/README.md 318 | index 7b45277..6b1993c 100644 319 | --- a/README.md 320 | +++ b/README.md 321 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 322 | `` 323 | # Bad (mixes English and Portuguese) 324 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 325 | -efefef Add `use` method to Credit model 326 | cdcdcd Agora vai 327 | `` 328 | 329 | +### Template 330 | + 331 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 332 | + 333 | ## Участие в проекте 334 | 335 | Any kind of help would be appreciated. Example of topics that you can help me with: 336 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 337 | 338 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 339 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 340 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 341 | ``` 342 | 343 | Мы можем выполнить `git add -p` чтобы добавить только те патчи, которые нам нужны, без необходимости изменять уже существующий код. 344 | Это очень полезно при разделении больших изменений в маленькие коммиты или для отмены/проверки конкретных изменений. 345 | 346 | ``` 347 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 348 | Split into 2 hunks. 349 | ``` 350 | 351 | #### часть 1 352 | 353 | ```diff 354 | @@ -186,7 +186,6 @@ 355 | `` 356 | # Bad (mixes English and Portuguese) 357 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 358 | -efefef Add `use` method to Credit model 359 | cdcdcd Agora vai 360 | `` 361 | 362 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 363 | ``` 364 | 365 | #### часть 2 366 | 367 | ```diff 368 | @@ -190,6 +189,10 @@ 369 | `` 370 | cdcdcd Agora vai 371 | `` 372 | 373 | +### Template 374 | + 375 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 376 | + 377 | ## Contributing 378 | 379 | Any kind of help would be appreciated. Example of topics that you can help me with: 380 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 381 | 382 | ``` 383 | 384 | #### часть 3 385 | 386 | ```diff 387 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 388 | 389 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 390 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 391 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 392 | ``` 393 | 394 | ## Кое-что интересное 395 | 396 | - https://whatthecommit.com/ 397 | - https://gitmoji.carloscuesta.me/ 398 | 399 | ## Нравится это руководство? 400 | 401 | [Скажи спасибо!](https://saythanks.io/to/RomuloOliveira) 402 | 403 | ## Помощь 404 | 405 | Любая помощь приветствуется. Вот, например, что вы можете сделать: 406 | 407 | - Исправить ошибки в грамматике и правописании 408 | - Перевод на другие языки 409 | - Улучшение списка связанных источников 410 | - Изменить неверную или неполную информацию 411 | 412 | ## Источники вдохновения и список для дальнейшего чтения 413 | 414 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 415 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 416 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 417 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 418 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 419 | -------------------------------------------------------------------------------- /README_tr-TR.md: -------------------------------------------------------------------------------- 1 | # Commit mesajları kılavuzu 2 | 3 | [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Commit mesajlarının önemini ve onların nasıl daha iyi yazılacağını anlatan bu kılavuz; commitin ne olduğunu, iyi commit mesajları yazmanın neden önemli olduğunu, iyi bir commit geçmişi planlamaya ve (yeniden) yazmaya yönelik bir takım örnekleri ve ipuçlarını anlamanıza yardımcı olabilir. 6 | 7 | ## "commit" nedir? 8 | 9 | Basitçe, commit yerel deponuza yazılan dosyalarınızın anlık görüntüsüdür. 10 | Bazı insanların düşündüğünün aksine, [git sadece dosyalar arasındaki farkı saklamaz, tüm dosyaların tam sürümünü saklar](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences). 11 | İki commit arasında değişmemiş dosyalar için, git zaten saklanan önceki özdeş dosyaya yalnızca bir bağlantı oluşturur. 12 | 13 | Aşağıdaki resimde git'in, her "versiyon"da commit edildiği durumda, verileri nasıl sakladığı gösterilmektedir: 14 | 15 | ![](https://i.stack.imgur.com/AQ5TG.png) 16 | 17 | ## Commit mesajları neden önemlidir? 18 | 19 | - Kod incelemelerini hızlandırır ve kolaylaştırır 20 | - Değişimin anlaşılmasına yardımcı olur 21 | - Sadece kodla açıklanamayan "neden"leri açıklar 22 | - Sonraki yazılımcıların, değişikliklerin neden ve nasıl yapıldığını anlamalarına yardımcı olur, sorun giderme ve hata ayıklamayı kolaylaştırır 23 | 24 | Bu faydaları en üst düzeye çıkarmak için, bir sonraki bölümde açıklanan bazı faydalı uygulamaları ve standartları kullanabiliriz. 25 | 26 | ## Faydalı uygulamalar 27 | 28 | Bunlar; deneyimlerimden, internetteki makalelerden ve diğer kılavuzlardan toplanan bazı uygulamalardır. Eklemek istedikleriniz varsa (veya bazılarına katılmıyorsanız) bir Pull Request açmaktan ve katkıda bulunmaktan çekinmeyin. 29 | 30 | ### Emir kipi kullanın 31 | 32 | ``` 33 | # Good 34 | Use InventoryBackendPool to retrieve inventory backend 35 | ``` 36 | 37 | ``` 38 | # Bad 39 | Used InventoryBackendPool to retrieve inventory backend 40 | ``` 41 | 42 | _Ama neden emir kipi?_ 43 | 44 | Bir commit mesajı belirtilen değişikliğin gerçekte ne yaptığını ve etkilerini açıklar, ne yapıldığını değil. 45 | 46 | ### Büyük harfle başlayın 47 | 48 | ``` 49 | # Good 50 | Add `use` method to Credit model 51 | ``` 52 | 53 | ``` 54 | # Bad 55 | add `use` method to Credit model 56 | ``` 57 | 58 | Büyük harfle başlanmasının nedeni, dil bilgisi kurallarından biri olan cümlelerin başında büyük harf kullanılması kuralına uymaktır. 59 | 60 | Bu uygulamanın kullanımı kişiden kişiye, takımdan takıma, hatta dilden dile değişebilir. Büyük harfle veya değil, önemli olan nokta tek bir standarda sadık kalmak ve onu takip etmektir. 61 | 62 | ### Kaynak koda bakmak zorunda kalmadan değişikliğin ne yaptığını bildirmeye çalışın 63 | 64 | ``` 65 | # Good 66 | Add `use` method to Credit model 67 | ``` 68 | 69 | ``` 70 | # Bad 71 | Add `use` method 72 | ``` 73 | 74 | ``` 75 | # Good 76 | Increase left padding between textbox and layout frame 77 | ``` 78 | 79 | ``` 80 | # Bad 81 | Adjust css 82 | ``` 83 | 84 | Bu uygulama mesajı okuyanların, commit edenin ne düşündüğünü anlamalarına yardımcı olmak adına birçok senaryoda (_örneğin çoklu commit'ler, çeşitli değişiklikler ve yeniden düzenlemeler_) faydalıdır. 85 | 86 | ### "Neden?", "Ne amaçla?", "Nasıl?"ı ve ek detayları açıklamak için mesaj gövdesini kullanın 87 | 88 | ``` 89 | # Good 90 | Fix method name of InventoryBackend child classes 91 | 92 | Classes derived from InventoryBackend were not 93 | respecting the base class interface. 94 | 95 | It worked because the cart was calling the backend implementation 96 | incorrectly. 97 | ``` 98 | 99 | ``` 100 | # Good 101 | Serialize and deserialize credits to json in Cart 102 | 103 | Convert the Credit instances to dict for two main reasons: 104 | 105 | - Pickle relies on file path for classes and we do not want to break up 106 | everything if a refactor is needed 107 | - Dict and built-in types are pickleable by default 108 | ``` 109 | 110 | ``` 111 | # Good 112 | Add `use` method to Credit 113 | 114 | Change from namedtuple to class because we need to 115 | setup a new attribute (in_use_amount) with a new value 116 | ``` 117 | 118 | Mesajların konusu ve gövdesi boş bir satırla ayrılır. 119 | Ek boş satırlar mesaj gövdesinin bir parçası olarak kabul edilir. 120 | 121 | `-`, `*` ve \` gibi karakterler okunabilirliği artıran öğelerdir. 122 | 123 | ### Herhangi bir bağlamı olmayan mesajlardan ve genel mesajlardan kaçının 124 | 125 | ``` 126 | # Bad 127 | Fix this 128 | 129 | Fix stuff 130 | 131 | It should work now 132 | 133 | Change stuff 134 | 135 | Adjust css 136 | ``` 137 | 138 | ### Karakter sayısını sınırlayın 139 | 140 | Konu için en fazla 50 karakter ve gövde için 72 karakter kullanılması [önerilir](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines). 141 | 142 | ### Dil tutarlılığını koruyun 143 | 144 | Proje sahipleri için: Bir dil seçin ve tüm commit mesajlarını bu dili kullanarak yazın. İdeal olarak, kod yorumları, varsayılan yerel çeviri ayarları (yerelleştirilmiş projeler için) vb. ile eşleşmelidir. 145 | 146 | Katkıda bulunanlar için: Var olan commit geçmişiyle aynı dili kullanarak commit mesajı yazın. 147 | 148 | ``` 149 | # Good 150 | ababab Add `use` method to Credit model 151 | efefef Use InventoryBackendPool to retrieve inventory backend 152 | bebebe Fix method name of InventoryBackend child classes 153 | ``` 154 | 155 | ``` 156 | # Good (Portekizce örneği) 157 | ababab Adiciona o método `use` ao model Credit 158 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 159 | bebebe Corrige nome de método na classe InventoryBackend 160 | ``` 161 | 162 | ``` 163 | # Bad (İngilizce ve Portekizce karışık) 164 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 165 | efefef Add `use` method to Credit model 166 | cdcdcd Agora vai 167 | ``` 168 | 169 | ### Şablon 170 | 171 | Bu şablonun orjinali [Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) tarafından yazıldı; [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 172 | 173 | ``` 174 | Summarize changes in around 50 characters or less 175 | 176 | More detailed explanatory text, if necessary. Wrap it to about 72 177 | characters or so. In some contexts, the first line is treated as the 178 | subject of the commit and the rest of the text as the body. The 179 | blank line separating the summary from the body is critical (unless 180 | you omit the body entirely); various tools like `log`, `shortlog` 181 | and `rebase` can get confused if you run the two together. 182 | 183 | Explain the problem that this commit is solving. Focus on why you 184 | are making this change as opposed to how (the code explains that). 185 | Are there side effects or other unintuitive consequences of this 186 | change? Here's the place to explain them. 187 | 188 | Further paragraphs come after blank lines. 189 | 190 | - Bullet points are okay, too 191 | 192 | - Typically a hyphen or asterisk is used for the bullet, preceded 193 | by a single space, with blank lines in between, but conventions 194 | vary here 195 | 196 | If you use an issue tracker, put references to them at the bottom, 197 | like this: 198 | 199 | Resolves: #123 200 | See also: #456, #789 201 | ``` 202 | 203 | ## Rebase vs. Merge 204 | 205 | Bu kısım Atlassian'ın ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) başlıklı harika eğitiminin bir TL;DR'si(Too long; didn't read/Çok uzundu; okumadım), özetidir. 206 | 207 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 208 | 209 | ### Rebase 210 | 211 | **TL;DR:** Branch commitlerinizi ana branchin devamına yeni bir ağaç oluşturacak şekilde tek tek uygular. 212 | 213 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 214 | 215 | ### Birleştirme 216 | 217 | **TL;DR:** _merge commit_ olarak adlandırılan ve iki branch arasında farklardan oluşan yeni bir commit oluşturur. 218 | 219 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 220 | 221 | ### Neden bazı kişiler merge yerine rebase tercih eder? 222 | 223 | Ben şahsen merge yerine rebase'i tercih ediyorum. Sebepleri ise şu şekilde: 224 | 225 | * Gereksiz bir _merge commit_'i olmadan "temiz" bir geçmiş oluşturur. 226 | * _Gördüğünüz şey, elde ettiğiniz şeydir_, yani bir kod incelemesinde, merge commit'inin ardında gizlenen değişikliklerden kaçınarak, tüm değişiklikler belirli ve başlıklı bir commit'ten gelir. 227 | * Daha fazla merge, commit eden tarafından çözümlenir ve her bir merge işlemi uygun bir mesajla bir commit içindedir. 228 | * Bir birleştirme commit'ini detaylı incelemek ve gözden geçirmek olağandışı bir durumdur, bu nedenle bunlardan kaçınmak tüm değişikliklerin ait oldukları bir commit'e sahip olmasını garanti eder. 229 | 230 | ### Ne zaman squash (ezme/birleştirme) yapılmalı? 231 | 232 | "Squashing" bir dizi commit'i alıp tek bir commit'e yoğunlaştırma işlemidir. 233 | 234 | Bazı durumlarda faydalıdır, örneğin: 235 | 236 | - Çok az ya da hiç bağlam olmadan commit'i azaltmak (yazım hatası düzeltmeleri, biçimlendirme, unutulmuş şeyler) 237 | - Birlikte uygulandığında daha anlamlı hale gelen ayrı değişiklikleri birleştirme 238 | - Üzerinde çalışılmaya devam edilen commit'leri yeniden yazma 239 | 240 | ### Rebase veya squash'dan ne zaman kaçınmalı? 241 | 242 | _Public commit_'te veya birden fazla kişinin çalıştığı, paylaşılan branchlerde rebase ve squash'den kaçının. Rebase ve squash geçmişi yeniden yazar ve var olan commit'lerin üzerine yazar, bunu paylaşılan branchlerde yapmak karşıklığa (örn., uzaktaki bir depoya push edilen/gönderilen commitler veya diğer branch/dallardan gelen commitler) neden olabilir ve insanlar farklı branchler ve çakışmalar nedeniyle değişikliklerini (hem yerel hem de uzaktan) kaybedebilir. 243 | 244 | ## Kullanışlı git komutları 245 | 246 | ### rebase -i 247 | 248 | Commitleri squash/sıkıştırmak, mesajları düzenlemek, commitleri yeniden yazmak/silmek/sıralarını düzenlemek vb. için kullanın. 249 | 250 | ``` 251 | pick 002a7cc Improve description and update document title 252 | pick 897f66d Add contributing section 253 | pick e9549cf Add a section of Available languages 254 | pick ec003aa Add "What is a commit" section" 255 | pick bbe5361 Add source referencing as a point of help wanted 256 | pick b71115e Add a section explaining the importance of commit messages 257 | pick 669bf2b Add "Good practices" section 258 | pick d8340d7 Add capitalization of first letter practice 259 | pick 925f42b Add a practice to encourage good descriptions 260 | pick be05171 Add a section showing good uses of message body 261 | pick d115bb8 Add generic messages and column limit sections 262 | pick 1693840 Add a section about language consistency 263 | pick 80c5f47 Add commit message template 264 | pick 8827962 Fix triple "m" typo 265 | pick 9b81c72 Add "Rebase vs Merge" section 266 | 267 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 268 | # 269 | # Commands: 270 | # p, pick = use commit 271 | # r, reword = use commit, but edit the commit message 272 | # e, edit = use commit, but stop for amending 273 | # s, squash = use commit, but meld into the previous commit 274 | # f, fixup = like "squash", but discard this commit's log message 275 | # x, exec = run command (the rest of the line) using shell 276 | # d, drop = remove commit 277 | # 278 | # These lines can be re-ordered; they are executed from top to bottom. 279 | # 280 | # If you remove a line here THAT COMMIT WILL BE LOST. 281 | # 282 | # However, if you remove everything, the rebase will be aborted. 283 | # 284 | # Note that empty commits are commented out 285 | ``` 286 | 287 | #### fixup 288 | 289 | Commitleri kolayca ve daha karmaşık bir rebase'e ihtiyaç duymadan temizlemek için kullanın. 290 | [Bu yazıda](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html), nasıl ve ne zaman yapılacağına dair güzel örnekler mevcut. 291 | 292 | ### cherry-pick 293 | 294 | Yanlış bir branch üzerinde yaptığınız commit'i tekrar kodlamaya gerek kalmadan uygulamak gerektiğinde çok kullanışlıdır. 295 | 296 | Örnek: 297 | 298 | ``` 299 | $ git cherry-pick 790ab21 300 | [master 094d820] Fix English grammar in Contributing 301 | Date: Sun Feb 25 23:14:23 2018 -0300 302 | 1 file changed, 1 insertion(+), 1 deletion(-) 303 | ``` 304 | 305 | ### add/checkout/reset [--patch | -p] 306 | 307 | Diyelim ki aşağıdaki gibi bir _diff_'imiz var: 308 | 309 | ```diff 310 | diff --git a/README.md b/README.md 311 | index 7b45277..6b1993c 100644 312 | --- a/README.md 313 | +++ b/README.md 314 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 315 | `` 316 | # Bad (mixes English and Portuguese) 317 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 318 | -efefef Credit modeline `use` metodu ekle 319 | cdcdcd Agora vai 320 | `` 321 | 322 | +### Template 323 | + 324 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 325 | + 326 | ## Contributing 327 | 328 | Any kind of help would be appreciated. Example of topics that you can help me with: 329 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 330 | 331 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 332 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 333 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 334 | ``` 335 | 336 | Zaten yazılmış olan kodu değiştirmeye gerek kalmadan, yalnızca istediğimiz yamaları eklemek için `git add-p`'yi kullanabiliriz. 337 | Büyük bir değişikliği daha küçük commitlere bölmek veya belirli değişiklikleri sıfırlamak/kontrol etmek açısından yararlıdır. 338 | 339 | ``` 340 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 341 | Split into 2 hunks. 342 | ``` 343 | 344 | #### hunk 1 345 | 346 | ```diff 347 | @@ -186,7 +186,6 @@ 348 | `` 349 | # Bad (mixes English and Portuguese) 350 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 351 | -efefef Credit modeline `use` metodu ekle 352 | cdcdcd Agora vai 353 | `` 354 | 355 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 356 | ``` 357 | 358 | #### hunk 2 359 | 360 | ```diff 361 | @@ -190,6 +189,10 @@ 362 | `` 363 | cdcdcd Agora vai 364 | `` 365 | 366 | +### Template 367 | + 368 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 369 | + 370 | ## Contributing 371 | 372 | Any kind of help would be appreciated. Example of topics that you can help me with: 373 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 374 | 375 | ``` 376 | 377 | #### hunk 3 378 | 379 | ```diff 380 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 381 | 382 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 383 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 384 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 385 | ``` 386 | 387 | ## Diğer ilginç bağlantılar 388 | 389 | - https://whatthecommit.com/ 390 | - https://gitmoji.carloscuesta.me/ 391 | 392 | ## Beğendin mi? 393 | 394 | [Teşekkür Et!](https://saythanks.io/to/RomuloOliveira) 395 | 396 | ## Katkıda bulunma 397 | 398 | Her türlü yardım makbule geçecektir. Bana yardımcı olabileceğiniz örnek konular: 399 | 400 | - Dil bilgisi ve imlâ düzeltmeleri 401 | - Diğer dillere çeviri 402 | - Kaynak/referans iyileştirme 403 | - Yanlış veya eksik bilgiyi düzeltme 404 | 405 | ## İlham alınanlar, kaynaklar ve ileri okuma 406 | 407 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 408 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 409 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 410 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 411 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 412 | -------------------------------------------------------------------------------- /README_ua-UA.md: -------------------------------------------------------------------------------- 1 | # Керівництво по написанню комітів 2 | 3 | [![Скажи дякую!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | Керівництво для розуміння важливості повідомлень комітів і того, як правильно їх писати. 6 | 7 | Це може допомогти вам зрозуміти, що таке коміт, чому важливо писати хороші повідомлення, кращі практики і деякі поради по плануванню і (пере)написанню хорошої історії комітів. 8 | 9 | ## Що таке "коміт"? 10 | 11 | Простими словами, коміт - це _знімок(зліпок)_ ваших локальних файлів, записаний в локальний репозиторій. 12 | Насправді, [git зберігає не тільки зміни між файлами, але і в цілому повну версію всіх файлів](https://git-scm.com/book/ru/v2/%D0%92%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5-%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D1%8B-Git). 13 | Для файлів, які не змінювались від одного коміта до іншого, git зберігає тільки посилання на попередній ідентичний файл, котрий вже був збережений. 14 | 15 | Зображення нижче показує, як git зберігає дані з плином часу, тоді як кожна "версія" являється комітом: 16 | 17 | ![](https://i.stack.imgur.com/AQ5TG.png) 18 | 19 | ## Чому повідомлення комітів важливі? 20 | 21 | - Щоб прискорити і спростити перевірку коду 22 | - Щоб допомогти в розумінні змін 23 | - Щоб прояснити речі, які не можуть бути описані тільки кодом 24 | - Щоб допомогти майбутнім розробникам розібратись, чому і як були зроблені зміни, полегшивши пошук і ліквідацію помилок 25 | 26 | Щоб досягнути максимального результату, ми можем використовувати деякі корисні практики та стандарти, описанні в наступному розділі. 27 | 28 | ## Корисні практики 29 | 30 | Це деякі практики, зібрані з мого досвіду, статей та решти керівництв. Якщо у вас є пропозиція (або ви не згідні з деякими речами) не соромтесь відкрити пулреквест і внести свій внесок. 31 | 32 | ### Використовуйте наказовий спосіб 33 | 34 | ``` 35 | # Добре 36 | Use InventoryBackendPool to retrieve inventory backend 37 | ``` 38 | 39 | ``` 40 | # Погано 41 | Used InventoryBackendPool to retrieve inventory backend 42 | ``` 43 | 44 | _Але навіщо використовувати наказовий спосіб?_ 45 | 46 | Повідомлення коміту описує, що конкретно **роблять** зафіксовані зміни, його кінцевий результат, а не що було зроблено. 47 | 48 | ### Починайте повідомлення коміту з Великої букви 49 | 50 | ``` 51 | # Добре 52 | Add `use` method to Credit model 53 | ``` 54 | 55 | ``` 56 | # Погано 57 | add `use` method to Credit model 58 | ``` 59 | 60 | Зміст цієї рекомендації простий: відповідно до правил граматики перше слово у реченні починається з великої букви. 61 | 62 | Використання цієї практики може варіюватись від людини до людини, від команди до команди або рідше від мови до мови. 63 | Велика чи ні, важливо дотримуватись єдиного стандарту і слідувати йому. 64 | 65 | ### Старайтесь описувати зміни так, щоб вказувати на сирцевий код, тобто місце де сталася зміна 66 | 67 | ``` 68 | # Добре 69 | Add `use` method to Credit model 70 | 71 | ``` 72 | 73 | ``` 74 | # Погано 75 | Add `use` method 76 | ``` 77 | 78 | ``` 79 | # Добре 80 | Increase left padding between textbox and layout frame 81 | ``` 82 | 83 | ``` 84 | # Погано 85 | Adjust css 86 | ``` 87 | 88 | Це корисно в багатьох випадках (пр. декілька комітів, різноманітні зміни і рефакторинг), щоб допомогти рев'юверам зрозуміти про що думав автор коміту, та що мав на увазі, коли писав повідомлення. 89 | 90 | ### Використовуйте тіло повідомлення для пояснення "чому", "для чого", "як" та додаткові деталі 91 | 92 | ``` 93 | # Добре 94 | Fix method name of InventoryBackend child classes 95 | 96 | Classes derived from InventoryBackend were not 97 | respecting the base class interface. 98 | 99 | It worked because the cart was calling the backend implementation 100 | incorrectly. 101 | ``` 102 | 103 | ``` 104 | # Добре 105 | Serialize and deserialize credits to json in Cart 106 | 107 | Convert the Credit instances to dict for two main reasons: 108 | 109 | - Pickle relies on file path for classes and we do not want to break up 110 | everything if a refactor is needed 111 | - Dict and built-in types are pickleable by default 112 | ``` 113 | 114 | ``` 115 | # Добре 116 | Add `use` method to Credit 117 | 118 | Change from namedtuple to class because we need to 119 | setup a new attribute (in_use_amount) with a new value 120 | ``` 121 | 122 | Тема і опис повідомлення розділені пустою стрічкою. 123 | 124 | Додаткові пусті стрічки рахуються частиною опису. 125 | 126 | Такі символи як `-`, `*` і ` покращують загальну читаємість. 127 | 128 | ### Запобігайте появі загальних повідомлень або повідомлень без будь-якого контексту 129 | 130 | ``` 131 | # Погано 132 | Fix this 133 | 134 | Fix stuff 135 | 136 | It should work now 137 | 138 | Change stuff 139 | 140 | Adjust css 141 | ``` 142 | 143 | ### Обмежте довжину стрічок 144 | 145 | [Рекомендуеться](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) використовувати максимум 50 символів для теми і 72 символа для опису. 146 | 147 | ### Зберігайте узгодженість мовлення 148 | 149 | Для власників проектів: Оберіть мову та пишіть всі повідомлення комітів використовуючи цю мову. В ідеалі, він має співпадати з коментарями в коді, стандартним перекладом (для перекладених проектів), і т.д. 150 | 151 | Для учасників проекту: Пишіть повідомлення комітів тією мовою, котра використовується в історії комітів. 152 | 153 | ``` 154 | # Добре 155 | ababab Add `use` method to Credit model 156 | efefef Use InventoryBackendPool to retrieve inventory backend 157 | bebebe Fix method name of InventoryBackend child classes 158 | ``` 159 | 160 | ``` 161 | # Добре (Португальський приклад) 162 | ababab Adiciona o método `use` ao model Credit 163 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 164 | bebebe Corrige nome de método na classe InventoryBackend 165 | ``` 166 | 167 | ``` 168 | # Погано (суміш Англійської та Португальської) 169 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 170 | efefef Add `use` method to Credit model 171 | cdcdcd Agora vai 172 | ``` 173 | 174 | ### Шаблон 175 | 176 | Цей шаблон, [ був з самого початку описаний Тімом Поупом (Tim Pope)](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), також згадується в [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 177 | 178 | ``` 179 | Summarize changes in around 50 characters or less 180 | 181 | More detailed explanatory text, if necessary. Wrap it to about 72 182 | characters or so. In some contexts, the first line is treated as the 183 | subject of the commit and the rest of the text as the body. The 184 | blank line separating the summary from the body is critical (unless 185 | you omit the body entirely); various tools like `log`, `shortlog` 186 | and `rebase` can get confused if you run the two together. 187 | 188 | Explain the problem that this commit is solving. Focus on why you 189 | are making this change as opposed to how (the code explains that). 190 | Are there side effects or other unintuitive consequences of this 191 | change? Here's the place to explain them. 192 | 193 | Further paragraphs come after blank lines. 194 | 195 | - Bullet points are okay, too 196 | 197 | - Typically a hyphen or asterisk is used for the bullet, preceded 198 | by a single space, with blank lines in between, but conventions 199 | vary here 200 | 201 | If you use an issue tracker, put references to them at the bottom, 202 | like this: 203 | 204 | Resolves: #123 205 | See also: #456, #789 206 | ``` 207 | 208 | ## Перебазування (Rebase) vs. Злиття (Merging) 209 | 210 | Цей розділ є коротким переказом чудового керівництва ["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) від Atlassian. 211 | 212 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 213 | 214 | ### Перебазування(Rebase) 215 | 216 | **Коротко:** Застосовує ваші коміти в гілці, один за другим, до базової гілки (наприклад, master), генеруючи нове дерево. 217 | 218 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 219 | 220 | ### Злиття (Merging) 221 | 222 | **Коротко:** Створює новий коміт, названий (відповідним чином) _коміт злиття_ (_merge commit_), з різницею між двома гілками. 223 | 224 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 225 | 226 | ### Чому деякі люди надають перевагу перебазуванню замість злиття? 227 | 228 | Я, особисто, надаю перевагу перебазуванню замість злиття. З наступних причин: 229 | 230 | * Це створює "чисту" історію, без непотрібних комітів-злиттів 231 | * _Що бачиш, те і маєш,_, т.е. при рев'ю коду всі зміни йдуть від певного коміту, без прихованих змін в комітах при злитті 232 | * Всі конфлікти при злитті вирішуються автором коміту, тому кожна злита зміна знаходиться в коміті з відповідним повідомленням 233 | * Зазвичай не дивляться на коміти-злиття, так що таким образом всі зміни зафіксовані в коміті, до якого вони безпосередньо відносяться 234 | 235 | ### Коли необхідно робити об'єднання комітів? 236 | 237 | Об'єднання (Squashing) — це процес об'єднання декількох комітів в один-єдиний коміт. 238 | 239 | Це може знадобитися в ряді ситуацій, наприклад: 240 | 241 | - Зменшення кількості комітів з невеликим контекстом або без контексту (виправлення опечатків, форматування, доповнення) 242 | - Об'єднання незалежних змін, котрі краще за все застосовувати разом 243 | - Переписування комітів в стадії _WIP_ (чорновика) 244 | 245 | ### Коли уникати перебазування або об'єднання (squash)? 246 | 247 | Уникайте цього в публічних комітах або в загальних гілках, в яких працюють кілька людей. 248 | Перебазування і об'єднання також перезаписує історію комітів і існуючі коміти, роблячи це з комітів, які знаходяться в різних гілках (наприклад, комітів, що відправлені в віддалений репозиторій або комітів з інших гілок) що може викликати плутанину і тому можна втратити зміни (як локальні, так і віддалені) через різницю дерева і конфліктів. 249 | 250 | ## Корисні команди git 251 | 252 | ### rebase -i 253 | 254 | Використовуйте їх, щоб об'єднати коміти, змінити повідомлення, переписати / видалити / змінити порядок комітів і т.д. 255 | 256 | ``` 257 | pick 002a7cc Improve description and update document title 258 | pick 897f66d Add contributing section 259 | pick e9549cf Add a section of Available languages 260 | pick ec003aa Add "What is a commit" section" 261 | pick bbe5361 Add source referencing as a point of help wanted 262 | pick b71115e Add a section explaining the importance of commit messages 263 | pick 669bf2b Add "Good practices" section 264 | pick d8340d7 Add capitalization of first letter practice 265 | pick 925f42b Add a practice to encourage good descriptions 266 | pick be05171 Add a section showing good uses of message body 267 | pick d115bb8 Add generic messages and column limit sections 268 | pick 1693840 Add a section about language consistency 269 | pick 80c5f47 Add commit message template 270 | pick 8827962 Fix triple "m" typo 271 | pick 9b81c72 Add "Rebase vs Merge" section 272 | 273 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 274 | # 275 | # Commands: 276 | # p, pick = use commit 277 | # r, reword = use commit, but edit the commit message 278 | # e, edit = use commit, but stop for amending 279 | # s, squash = use commit, but meld into the previous commit 280 | # f, fixup = like "squash", but discard this commit's log message 281 | # x, exec = run command (the rest of the line) using shell 282 | # d, drop = remove commit 283 | # 284 | # These lines can be re-ordered; they are executed from top to bottom. 285 | # 286 | # If you remove a line here THAT COMMIT WILL BE LOST. 287 | # 288 | # However, if you remove everything, the rebase will be aborted. 289 | # 290 | # Note that empty commits are commented out 291 | ``` 292 | 293 | #### fixup 294 | 295 | Використовуйте цю команду, щоб привести в порядок коміти, не використовуючи перебазування. 296 | В [цій статті](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) є гарні приклади того, як і коли це робити. 297 | 298 | 299 | ### cherry-pick 300 | 301 | Ця команда може бути дуже корисною для зміни коміту, який був зроблений в неправильній гілці, щоб не писати код заново. 302 | 303 | Приклад: 304 | 305 | ``` 306 | $ git cherry-pick 790ab21 307 | [master 094d820] Fix English grammar in Contributing 308 | Date: Sun Feb 25 23:14:23 2018 -0300 309 | 1 file changed, 1 insertion(+), 1 deletion(-) 310 | ``` 311 | 312 | ### add/checkout/reset [--patch | -p] 313 | 314 | Давайте уявимо, що у нас є наступний список відмінностей: 315 | 316 | ```diff 317 | diff --git a/README.md b/README.md 318 | index 7b45277..6b1993c 100644 319 | --- a/README.md 320 | +++ b/README.md 321 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 322 | `` 323 | # Bad (mixes English and Portuguese) 324 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 325 | -efefef Add `use` method to Credit model 326 | cdcdcd Agora vai 327 | `` 328 | 329 | +### Template 330 | + 331 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 332 | + 333 | ## Участь у проекті 334 | 335 | Any kind of help would be appreciated. Example of topics that you can help me with: 336 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 337 | 338 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 339 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 340 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 341 | ``` 342 | 343 | Ми можемо виконати `git add -p` щоб додати тільки ті патчі, які нам потрібні, без необхідності змінювати вже існуючий код. 344 | Це дуже корисно при розділенні великих змін в маленькі коміти або для відміни/перевірки конкретних змін. 345 | 346 | ``` 347 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 348 | Split into 2 hunks. 349 | ``` 350 | 351 | #### частина 1 352 | 353 | ```diff 354 | @@ -186,7 +186,6 @@ 355 | `` 356 | # Bad (mixes English and Portuguese) 357 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 358 | -efefef Add `use` method to Credit model 359 | cdcdcd Agora vai 360 | `` 361 | 362 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 363 | ``` 364 | 365 | #### частина 2 366 | 367 | ```diff 368 | @@ -190,6 +189,10 @@ 369 | `` 370 | cdcdcd Agora vai 371 | `` 372 | 373 | +### Template 374 | + 375 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 376 | + 377 | ## Contributing 378 | 379 | Any kind of help would be appreciated. Example of topics that you can help me with: 380 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 381 | 382 | ``` 383 | 384 | #### частина 3 385 | 386 | ```diff 387 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 388 | 389 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 390 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 391 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 392 | ``` 393 | 394 | ## Дещо цікаве 395 | 396 | - https://whatthecommit.com/ 397 | - https://gitmoji.carloscuesta.me/ 398 | 399 | ## Подобається це керівництво? 400 | 401 | [Скажи Дякую!](https://saythanks.io/to/RomuloOliveira) 402 | 403 | ## Допомога 404 | 405 | Люба допомога вітається. Ось, наприклад, Що ви можете зробити: 406 | 407 | - Виправити помилки в граматиці та правописі 408 | - Переклад на інші мови 409 | - Покращення списку пов'язаних джерел 410 | - Змінити неправильну або неповну інформацію 411 | 412 | ## Джерела натхнення та список для подальшого читання 413 | 414 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 415 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 416 | - [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 417 | - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 418 | - [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 419 | -------------------------------------------------------------------------------- /README_zh-CN.md: -------------------------------------------------------------------------------- 1 | # Commit messages guide 2 | 3 | [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | 一个了解 commit 信息重要性和如何更好地编写它的指南。 6 | 7 | 它可以帮助你了解什么是 commit、为什么编写好的信息很重要、最好的实践案例以及一些技巧来计划和（重新）编写良好的 commit 历史。 8 | 9 | ## 什么是“commit”？ 10 | 11 | 简单来讲，commit 就是在本地存储库中编写的文件的 _快照_。与印象中不同的是，[git 不仅存储不同版本文件之间的差异，还存储了所有文件的完整版本](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences)。对于两个 commit 之间没有被修改的文件，git 只存储指向前一个完全相同的文件的链接。 12 | 13 | 下面的图片展示了 git 如何随着时间存储数据，其中每个 “Version” 都是一个 commit： 14 | 15 | ![](https://i.stack.imgur.com/AQ5TG.png) 16 | 17 | ## 为什么 commit 信息很重要？ 18 | 19 | - 加快和简化代码审查（code reviews） 20 | - 帮助理解一个更改 21 | - 解释不能只由代码描述的“为什么” 22 | - 帮助未来的维护人员弄清楚为什么以及如何产生的更改，从而使故障排查和调试更容易 23 | 24 | 为了最大化这些结果，我们可以使用下一节中描述的一些好的实践和标准。 25 | 26 | ## 好的实践 27 | 28 | 这些是从我的经验、互联网文章和其他指南中整理的一些实践经验。如果你有更多的经验（或持不同意见），请随时提交 Pull Request 提供帮助。 29 | 30 | ### 使用祈使句 31 | 32 | ``` 33 | # Good 34 | Use InventoryBackendPool to retrieve inventory backend 35 | 用 InventoryBackendPool 获取库存 36 | ``` 37 | 38 | ``` 39 | # Bad 40 | Used InventoryBackendPool to retrieve inventory backend 41 | InventoryBackendPool 被用于获取库存 42 | ``` 43 | 44 | _不过为什么要使用祈使句呢？_ 45 | 46 | commit 信息描述的是引用的变更部分实际上**做**了什么，它的效果，而不是因此被做了什么。 47 | 48 | ### 首字母大写 49 | 50 | ``` 51 | # Good 52 | Add `use` method to Credit model 53 | ``` 54 | 55 | ``` 56 | # Bad 57 | add `use` method to Credit model 58 | ``` 59 | 60 | 首字母大写的原因是遵守英文句子开头使用大写字母的语法规则。 61 | 62 | 这种做法可能因人而异、因团队而异、甚至因语言而异。不管是否大写，重要的是要制定一个标准并遵守它。 63 | 64 | ### 尽量做到只看注释便可明白而无需查看变更内容 65 | 66 | ``` 67 | # Good 68 | Add `use` method to Credit model 69 | 为 Credit 模块添加 `use` 方法 70 | 71 | ``` 72 | 73 | ``` 74 | # Bad 75 | Add `use` method 76 | 添加 `use` 方法 77 | ``` 78 | 79 | ``` 80 | # Good 81 | Increase left padding between textbox and layout frame 82 | 在 textbox 和 layout frame 之间添加向左对齐 83 | ``` 84 | 85 | ``` 86 | # Bad 87 | Adjust css 88 | 就改了下 css 89 | ``` 90 | 91 | 它在许多场景中（例如多次 commit、多个更改和重构）非常有用，可以帮助审查人员理解提交者的想法。 92 | 93 | ### 使用信息本身来解释“原因”、“目的”、“手段”和其他的细节 94 | 95 | ``` 96 | # Good 97 | Fix method name of InventoryBackend child classes 98 | 99 | Classes derived from InventoryBackend were not 100 | respecting the base class interface. 101 | 102 | It worked because the cart was calling the backend implementation 103 | incorrectly. 104 | ``` 105 | 106 | ``` 107 | # Good 108 | Serialize and deserialize credits to json in Cart 109 | 110 | Convert the Credit instances to dict for two main reasons: 111 | 112 | - Pickle relies on file path for classes and we do not want to break up 113 | everything if a refactor is needed 114 | - Dict and built-in types are pickleable by default 115 | ``` 116 | 117 | ``` 118 | # Good 119 | Add `use` method to Credit 120 | 121 | Change from namedtuple to class because we need to 122 | setup a new attribute (in_use_amount) with a new value 123 | ``` 124 | 125 | 信息的主题和正文之间用空行隔开。其他空行被视为信息正文的一部分。 126 | 127 | 像“-”、“*”和“\”这样的字符可以提高可读性。 128 | 129 | ### 避免使用无上下文的信息 130 | 131 | ``` 132 | # Bad 133 | Fix this 134 | 135 | Fix stuff 136 | 137 | It should work now 138 | 139 | Change stuff 140 | 141 | Adjust css 142 | ``` 143 | 144 | ### 限制每行字数 145 | 146 | [这里建议](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)主题最多使用50个字符，正文最多使用72个字符。 147 | 148 | ### 保持语言的一致性 149 | 150 | 对于项目所有者而言：选择一种语言并使用该语言编写所有的 commit 信息。理想情况下，它应与代码注释、默认翻译区域（用于本地化项目）等相匹配。 151 | 152 | 对于贡献者而言：使用与现有 commit 历史相同的语言编写 commit 信息。 153 | 154 | ``` 155 | # Good 156 | ababab Add `use` method to Credit model 157 | efefef Use InventoryBackendPool to retrieve inventory backend 158 | bebebe Fix method name of InventoryBackend child classes 159 | ``` 160 | 161 | ``` 162 | # Good (Portuguese example) 163 | ababab Adiciona o método `use` ao model Credit 164 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 165 | bebebe Corrige nome de método na classe InventoryBackend 166 | ``` 167 | 168 | ``` 169 | # Bad (mixes English and Portuguese) 170 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 171 | efefef Add `use` method to Credit model 172 | cdcdcd Agora vai 173 | ``` 174 | 175 | ### 模板 176 | 177 | 下面是参考模板，最初由 [Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 编写，出现在 [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) 中。 178 | 179 | ``` 180 | 用 50 左右或更少的字符描述更改 181 | 182 | 如有必要，可提供更详细的补充说明，并尽可能将其限定在每行 72 个字符左右。 183 | 在某些情况下，第一行被视为 commit 的主题，文本其余部分被作为正文。 184 | 因此，将主题从正文分割出来的空白行就显得至关重要(除非完全省略正文)。 185 | 如若不然，在使用命令行，如 “log”，“shortlog” 以及 “rebase” 的时候，将会很容易混淆。 186 | 187 | 解释当前 commit 所解决的问题。 188 | 请重点描述产生此更改的原因，而非手段（代码解释了一切）。 189 | 是否存在副作用以及其他不直观的影响？ 190 | 请在这里将其解释清楚。 191 | 192 | 接下来请另起一行。 193 | 194 | - 也可以使用列举要点的格式。 195 | 196 | - 通常使用连字符(-)或星号(*)作为要点段落标记，标记与文本之间留一空格，各要点之间留一空行。但这取决于你们的约定。 197 | 198 | 如果你使用问题跟踪器，请将对它们的引用放在底部，如下所示: 199 | 200 | Resolves: #123 201 | See also: #456, #789 202 | ``` 203 | 204 | ## Rebase vs. Merge 205 | 206 | 这部分是 Atlassian 的优秀教程(TL;DR)——["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 的精华。 207 | 208 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 209 | 210 | ### Rebase 211 | 212 | **TL;DR:** 将你的分支逐个应用于基本分支，生成新树。 213 | 214 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 215 | 216 | ### Merge 217 | 218 | **TL;DR:** 创建一个新的 commit，称为 _merge commit_（合并提交），其具有两个分支之间的差异。 219 | 220 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 221 | 222 | ### 为什么一些人更喜欢 rebase 而非 merge？ 223 | 224 | 我特别喜欢 rebase 而不是 merge。原因有以下几点： 225 | 226 | * 它的历史信息很"干净"，没有无用的合并 commit。 227 | * _所见即所得_，即在代码审查中，所有的更改都能在特定的、有标题的 commit 中找到，避免了隐藏在合并 commit 中的修改。 228 | * 通常 merge 是由提交者实行的，并会为每个转换成 commit 的 merge 书写准确的信息。 229 | * 通常我们不会深挖和复查 merge commit，因此尽量避免使用 merge commit，并确保个变化点都有它们所属的 commit 。 230 | 231 | ### 什么时候 squash 232 | 233 | “Squashing” 是将一系列 commit 压缩成一个的过程。 234 | 235 | 它在某些情况下很有用，例如： 236 | 237 | - 减少那些很少甚至没有上下文（拼写错误、格式化、缺失内容）的 commit 238 | - 将单独的更改连接在一起使它们更通俗易懂 239 | - 重写 _work in progress_ 的 commit 240 | 241 | ### 什么时候避免 rebase 或 squash 242 | 243 | 避免在多人共同开发的公共 commit 或共享分支上使用 rebase 和 squash。rebase 和 squash 会改写历史记录并覆盖当前 commit，在共享分支的 commit（即推送到远程仓库或来自其他分支的 commit）上执行这些操作可能会引起混乱，由于分支产生分歧及冲突，合作者可能会因此失去他们（本地和远程）的更改。 244 | 245 | ## 有用的 git 命令 246 | 247 | ### rebase -i 248 | 249 | 使用它来压缩提交（squash commits）、 编写信息、 重写/删除/重新编排 commit 等。 250 | 251 | ``` 252 | pick 002a7cc Improve description and update document title 253 | pick 897f66d Add contributing section 254 | pick e9549cf Add a section of Available languages 255 | pick ec003aa Add "What is a commit" section" 256 | pick bbe5361 Add source referencing as a point of help wanted 257 | pick b71115e Add a section explaining the importance of commit messages 258 | pick 669bf2b Add "Good practices" section 259 | pick d8340d7 Add capitalization of first letter practice 260 | pick 925f42b Add a practice to encourage good descriptions 261 | pick be05171 Add a section showing good uses of message body 262 | pick d115bb8 Add generic messages and column limit sections 263 | pick 1693840 Add a section about language consistency 264 | pick 80c5f47 Add commit message template 265 | pick 8827962 Fix triple "m" typo 266 | pick 9b81c72 Add "Rebase vs Merge" section 267 | 268 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 269 | # 270 | # Commands: 271 | # p, pick = use commit 272 | # r, reword = use commit, but edit the commit message 273 | # e, edit = use commit, but stop for amending 274 | # s, squash = use commit, but meld into the previous commit 275 | # f, fixup = like "squash", but discard this commit's log message 276 | # x, exec = run command (the rest of the line) using shell 277 | # d, drop = remove commit 278 | # 279 | # These lines can be re-ordered; they are executed from top to bottom. 280 | # 281 | # If you remove a line here THAT COMMIT WILL BE LOST. 282 | # 283 | # However, if you remove everything, the rebase will be aborted. 284 | # 285 | # Note that empty commits are commented out 286 | ``` 287 | 288 | #### fixup 289 | 290 | 使用它可以轻松清理 commit，而不需要复杂的 rebase。[这篇文章](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html)提供了很好的示例，说明了如何以及何时进行此操作。 291 | 292 | ### cherry-pick 293 | 294 | 它在你 commit 到了错误的分支而不需要重新编码时非常有用。 295 | 296 | 例子： 297 | 298 | ``` 299 | $ git cherry-pick 790ab21 300 | [master 094d820] Fix English grammar in Contributing 301 | Date: Sun Feb 25 23:14:23 2018 -0300 302 | 1 file changed, 1 insertion(+), 1 deletion(-) 303 | ``` 304 | 305 | ### add/checkout/reset [--patch | -p] 306 | 307 | 假设我们有以下冲突： 308 | 309 | ```diff 310 | diff --git a/README.md b/README.md 311 | index 7b45277..6b1993c 100644 312 | --- a/README.md 313 | +++ b/README.md 314 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 315 | `` 316 | # Bad (mixes English and Portuguese) 317 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 318 | -efefef Add `use` method to Credit model 319 | cdcdcd Agora vai 320 | `` 321 | 322 | +### Template 323 | + 324 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 325 | + 326 | ## Contributing 327 | 328 | Any kind of help would be appreciated. Example of topics that you can help me with: 329 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 330 | 331 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 332 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 333 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 334 | ``` 335 | 336 | 我们可以使用 `git add -p` 只添加我们想要的补丁，而无需更改已有代码。 337 | 它在将一个大的更改分解为小的 commit 或 reset/checkout 特定的更改时很有用。 338 | 339 | ``` 340 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 341 | Split into 2 hunks. 342 | ``` 343 | 344 | #### hunk 1 345 | 346 | ```diff 347 | @@ -186,7 +186,6 @@ 348 | `` 349 | # Bad (mixes English and Portuguese) 350 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 351 | -efefef Add `use` method to Credit model 352 | cdcdcd Agora vai 353 | `` 354 | 355 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 356 | ``` 357 | 358 | #### hunk 2 359 | 360 | ```diff 361 | @@ -190,6 +189,10 @@ 362 | `` 363 | cdcdcd Agora vai 364 | `` 365 | 366 | +### Template 367 | + 368 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 369 | + 370 | ## Contributing 371 | 372 | Any kind of help would be appreciated. Example of topics that you can help me with: 373 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 374 | 375 | ``` 376 | 377 | #### hunk 3 378 | 379 | ```diff 380 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 381 | 382 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 383 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 384 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 385 | ``` 386 | 387 | ## 其他有趣的内容 388 | 389 | https://whatthecommit.com/ 390 | 391 | ## 喜欢它吗？ 392 | 393 | [点赞！](https://saythanks.io/to/RomuloOliveira) 394 | 395 | ## 贡献 396 | 397 | 感谢任何形式的帮助。例如： 398 | 399 | - 语法和拼写的纠正 400 | - 翻译成其他语言 401 | - 原引用的改进 402 | - 不正确或不完整的信息 403 | 404 | ## 灵感、来源以及扩展阅读 405 | 406 | - [如何编写 Git Commit Message](https://chris.beams.io/posts/git-commit/) 407 | - [Pro Git Book - Commit 指南](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 408 | - [关于 Git Commit Messages 的说明](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 409 | - [合并与变基](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 410 | - [Pro Git Book - 改写历史](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 411 | -------------------------------------------------------------------------------- /README_zh-TW.md: -------------------------------------------------------------------------------- 1 | # Commit messages guide 2 | 3 | [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira) 4 | 5 | 這是一份了解 commit 訊息的重要性和如何更好的撰寫它的指導手冊。 6 | 7 | 它可以幫助你了解什麼是 commit、為什麼撰寫好的訊息很重要、最好的實踐案例以及一些技巧來計劃和 (重新) 撰寫良好的 commit 紀錄。 8 | 9 | ## 什麼是“commit”？ 10 | 11 | 簡單來說，commit 就是在本地資料庫中撰寫的檔案的 _快照_。與印象中不同的是，[git 不僅儲存不同版本檔案之間的差異，還儲存了所有檔案的完整版本](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences)。對於兩個 commit 之間沒有被修改的檔案，git 只儲存指向前一個完全相同的檔案的連結。 12 | 13 | 下面的圖片展示了 git 如何隨著時間儲存資料，其中每個 “Version” 都是一個 commit： 14 | 15 | ![](https://i.stack.imgur.com/AQ5TG.png) 16 | 17 | ## 為什麼 commit 資訊很重要？ 18 | 19 | - 加快和簡化 code review 20 | - 幫助理解一個變更 21 | - 解釋那些無法只透過程式碼來描述的“為什麼” 22 | - 幫助未來的維護人員明白為什麼以及如何產生的變更，從而使問題排查和除錯更容易 23 | 24 | 為了最好的效果，我們可以使用下一節中描述的一些好的實踐方式和標準。 25 | 26 | ## 好的實踐方式 27 | 28 | 這些是從我的經驗、網路文章和其他指導中整理的一些實踐經驗。如果你有更多的經驗（或持不同意見），請隨時提交 Pull Request 來提供幫助。 29 | 30 | ### 使用祈使句 31 | 32 | ``` 33 | # Good 34 | Use InventoryBackendPool to retrieve inventory backend 35 | 用 InventoryBackendPool 取得存貨 36 | ``` 37 | 38 | ``` 39 | # Bad 40 | Used InventoryBackendPool to retrieve inventory backend 41 | InventoryBackendPool 被用於取得存貨 42 | ``` 43 | 44 | _不過為什麼要使用祈使句呢？_ 45 | 46 | commit 訊息描述的效果是這個變更實際上**做**了什麼，而不是被做了什麼。 47 | 48 | ### 第一個字母大寫 49 | 50 | ``` 51 | # Good 52 | Add `use` method to Credit model 53 | ``` 54 | 55 | ``` 56 | # Bad 57 | add `use` method to Credit model 58 | ``` 59 | 60 | 第一個字母大寫的原因是遵守英文句子開頭使用大寫字母的語法規則。 61 | 62 | 這種做法可能因人而異、因團隊而異、甚至因語言而異。不管是否大寫，重要的是要制定一個標準並遵守它。 63 | 64 | ### 僅量做到只看到註釋就可以明白而無需查看變更內容 65 | 66 | ``` 67 | # Good 68 | Add `use` method to Credit model 69 | 為 Credit 模型增加 `use` 方法 70 | 71 | ``` 72 | 73 | ``` 74 | # Bad 75 | Add `use` method 76 | 增加 `use` 方法 77 | ``` 78 | 79 | ``` 80 | # Good 81 | Increase left padding between textbox and layout frame 82 | 在 textbox 和 layout frame 之間增加向左對齊 83 | ``` 84 | 85 | ``` 86 | # Bad 87 | Adjust css 88 | 調整 css 89 | ``` 90 | 91 | 它在許多場景中（例如多次 commit、多個變更和重構）非常有用，可以幫助審查者理解提交者的想法。 92 | 93 | ### 使用訊息本身來解釋“原因”、“目的”、“方式”和其他的細節 94 | 95 | ``` 96 | # Good 97 | Fix method name of InventoryBackend child classes 98 | 99 | Classes derived from InventoryBackend were not 100 | respecting the base class interface. 101 | 102 | It worked because the cart was calling the backend implementation 103 | incorrectly. 104 | ``` 105 | 106 | ``` 107 | # Good 108 | Serialize and deserialize credits to json in Cart 109 | 110 | Convert the Credit instances to dict for two main reasons: 111 | 112 | - Pickle relies on file path for classes and we do not want to break up 113 | everything if a refactor is needed 114 | - Dict and built-in types are pickleable by default 115 | ``` 116 | 117 | ``` 118 | # Good 119 | Add `use` method to Credit 120 | 121 | Change from namedtuple to class because we need to 122 | setup a new attribute (in_use_amount) with a new value 123 | ``` 124 | 125 | 訊息的標題和內容之間用空白行隔開。其他空白行被視為訊息內容的一部分。 126 | 127 | 像“-”、“*”和“\”這樣的符號可以提高可讀性。 128 | 129 | ### 避免使用沒有上下文的訊息 130 | 131 | ``` 132 | # Bad 133 | Fix this 134 | 135 | Fix stuff 136 | 137 | It should work now 138 | 139 | Change stuff 140 | 141 | Adjust css 142 | ``` 143 | 144 | ### 限制每行字數 145 | 146 | [這裡建議](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)標題最多使用50個字，內容最多使用72個字。 147 | 148 | ### 保持語言的一致性 149 | 150 | 對於專案所有者而言：選擇一種語言並使用該語言撰寫所有的 commit 訊息。理想情況下，它應與程式碼註解、預設翻譯地區 (用於本地化專案) 等相匹配。 151 | 152 | 對於貢獻者而言：使用與既有 commit 紀錄相同的語言撰寫 commit 訊息。 153 | 154 | ``` 155 | # Good 156 | ababab Add `use` method to Credit model 157 | efefef Use InventoryBackendPool to retrieve inventory backend 158 | bebebe Fix method name of InventoryBackend child classes 159 | ``` 160 | 161 | ``` 162 | # Good (Portuguese example) 163 | ababab Adiciona o método `use` ao model Credit 164 | efefef Usa o InventoryBackendPool para recuperar o backend de estoque 165 | bebebe Corrige nome de método na classe InventoryBackend 166 | ``` 167 | 168 | ``` 169 | # Bad (mixes English and Portuguese) 170 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 171 | efefef Add `use` method to Credit model 172 | cdcdcd Agora vai 173 | ``` 174 | 175 | ### 範本 176 | 177 | 下面是參考範本，最初由 [Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 撰寫，出現在 [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) 中。 178 | 179 | ``` 180 | 用 50 個左右或更少的字來描述變更 181 | 182 | 如有必要，可以提供更詳細的補充說明，並儘可能將其限定在每行 72 個字左右。 183 | 在某些情況下，第一行被視為 commit 的標題，其餘的文字被視為內容主體。 184 | 因此，將標題從內容分離出來的空白行就顯得非常重要(除非完全省略內容)。 185 | 如若不然，在使用命令列，如 “log”，“shortlog” 以及 “rebase” 的時候，將會很容易混淆。 186 | 187 | 解釋當前 commit 所解決的問題。 188 | 請重點描述產生此變更的原因，而非方式（程式碼解釋了一切）。 189 | 是否存在副作用以及其他隱含的影響？ 190 | 請在這裡將其解釋清楚。 191 | 192 | 接下來請另起一行。 193 | 194 | - 也可以使用列舉的格式 (bullet point)。 195 | 196 | - 通常使用連字號(-)或星號(*)作為要點段落標記，標記與內容之間留一空格，各要點之間留一空白行。但這取決於你們的約定。 197 | 198 | 如果你使用問題追蹤器，請將對它們的引用放在底部，如下所示: 199 | 200 | Resolves: #123 201 | See also: #456, #789 202 | ``` 203 | 204 | ## Rebase vs. Merge 205 | 206 | 這部分是 Atlassian 的優秀教學(TL;DR)——["Merging vs. Rebasing"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 的精華。 207 | 208 | ![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq) 209 | 210 | ### Rebase 211 | 212 | **TL;DR:** 將你的分支逐個應用於基本分支，生成新樹。 213 | 214 | ![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq) 215 | 216 | ### Merge 217 | 218 | **TL;DR:** 建立一個新的 commit，稱為 _merge commit_（合併提交），其具有兩個分支之間的差異。 219 | 220 | ![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq) 221 | 222 | ### 為什麼一些人更喜歡 rebase 而非 merge？ 223 | 224 | 我特別喜歡 rebase 而不是 merge。原因有以下幾點： 225 | 226 | * 它的歷史紀錄很"乾淨"，沒有無用的合併 commit。 227 | * _所見即所得_，即在程式碼審查中，所有的變更都能在特定的、有標題的 commit 中找到，避免藏在合併 commit 中的修改。 228 | * 通常 merge 是由提交者執行的，並會為每個轉換成 commit 的 merge 寫準確的訊息。 229 | * 通常我們不會深挖和複查 merge commit，因此儘量避免使用 merge commit，並確保每個變化點都有它們所屬的 commit 。 230 | 231 | ### 什麼時候 squash 232 | 233 | “Squashing” 是將一系列 commit 壓縮成一個的過程。 234 | 235 | 它在某些情況下很有用，例如： 236 | 237 | - 減少那些很少甚至沒有上下文（拼寫錯誤、格式化、遺失內容）的 commit 238 | - 將單獨的變更連結在一起使它們更通俗易懂 239 | - 重寫 _work in progress_ 的 commit 240 | 241 | ### 什麼時候避免使用 rebase 或 squash 242 | 243 | 避免在多人共同開發的共用 commit 或共享分支上使用 rebase 和 squash。rebase 和 squash 會改寫歷史紀錄並覆寫當前的 commit，在共享分支 commit（即推送到遠端倉庫或來自其他分支的 commit）上執行這些操作可能會引起混亂，由於分支產生分岐及衝突，合作者可能會因此失去它們（本地和遠端）的更改。 244 | 245 | ## 有用的 git 指令 246 | 247 | ### rebase -i 248 | 249 | 使用它來壓縮提交（squash commits）、撰寫訊息、重寫/刪除/重新編排 commit 等。 250 | 251 | ``` 252 | pick 002a7cc Improve description and update document title 253 | pick 897f66d Add contributing section 254 | pick e9549cf Add a section of Available languages 255 | pick ec003aa Add "What is a commit" section" 256 | pick bbe5361 Add source referencing as a point of help wanted 257 | pick b71115e Add a section explaining the importance of commit messages 258 | pick 669bf2b Add "Good practices" section 259 | pick d8340d7 Add capitalization of first letter practice 260 | pick 925f42b Add a practice to encourage good descriptions 261 | pick be05171 Add a section showing good uses of message body 262 | pick d115bb8 Add generic messages and column limit sections 263 | pick 1693840 Add a section about language consistency 264 | pick 80c5f47 Add commit message template 265 | pick 8827962 Fix triple "m" typo 266 | pick 9b81c72 Add "Rebase vs Merge" section 267 | 268 | # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) 269 | # 270 | # Commands: 271 | # p, pick = use commit 272 | # r, reword = use commit, but edit the commit message 273 | # e, edit = use commit, but stop for amending 274 | # s, squash = use commit, but meld into the previous commit 275 | # f, fixup = like "squash", but discard this commit's log message 276 | # x, exec = run command (the rest of the line) using shell 277 | # d, drop = remove commit 278 | # 279 | # These lines can be re-ordered; they are executed from top to bottom. 280 | # 281 | # If you remove a line here THAT COMMIT WILL BE LOST. 282 | # 283 | # However, if you remove everything, the rebase will be aborted. 284 | # 285 | # Note that empty commits are commented out 286 | ``` 287 | 288 | #### fixup 289 | 290 | 使用它可以輕鬆清理 commit，而不需要複雜的 rebase。[這篇文章](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html)提供了很好的範例，說明了如何以及何時進行此操作。 291 | 292 | ### cherry-pick 293 | 294 | 它在你 commit 到了錯誤的分支而不需要重新撰寫程式碼時非常有用。 295 | 296 | 例子： 297 | 298 | ``` 299 | $ git cherry-pick 790ab21 300 | [master 094d820] Fix English grammar in Contributing 301 | Date: Sun Feb 25 23:14:23 2018 -0300 302 | 1 file changed, 1 insertion(+), 1 deletion(-) 303 | ``` 304 | 305 | ### add/checkout/reset [--patch | -p] 306 | 307 | 假設我們有以下衝突： 308 | 309 | ```diff 310 | diff --git a/README.md b/README.md 311 | index 7b45277..6b1993c 100644 312 | --- a/README.md 313 | +++ b/README.md 314 | @@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend 315 | `` 316 | # Bad (mixes English and Portuguese) 317 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 318 | -efefef Add `use` method to Credit model 319 | cdcdcd Agora vai 320 | `` 321 | 322 | +### Template 323 | + 324 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 325 | + 326 | ## Contributing 327 | 328 | Any kind of help would be appreciated. Example of topics that you can help me with: 329 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 330 | 331 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 332 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 333 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 334 | ``` 335 | 336 | 我們可以使用 `git add -p` 只加入我們想要的更新，而無需更改已有的程式碼。 337 | 它在將一個大的變更分解為小的 commit 或 reset/checkout 特定的變更時很有用。 338 | 339 | ``` 340 | Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s 341 | Split into 2 hunks. 342 | ``` 343 | 344 | #### hunk 1 345 | 346 | ```diff 347 | @@ -186,7 +186,6 @@ 348 | `` 349 | # Bad (mixes English and Portuguese) 350 | ababab Usa o InventoryBackendPool para recuperar o backend de estoque 351 | -efefef Add `use` method to Credit model 352 | cdcdcd Agora vai 353 | `` 354 | 355 | Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? 356 | ``` 357 | 358 | #### hunk 2 359 | 360 | ```diff 361 | @@ -190,6 +189,10 @@ 362 | `` 363 | cdcdcd Agora vai 364 | `` 365 | 366 | +### Template 367 | + 368 | +This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project). 369 | + 370 | ## Contributing 371 | 372 | Any kind of help would be appreciated. Example of topics that you can help me with: 373 | Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]? 374 | 375 | ``` 376 | 377 | #### hunk 3 378 | 379 | ```diff 380 | @@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi 381 | 382 | - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) 383 | - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 384 | +- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 385 | ``` 386 | 387 | ## 其他有趣的內容 388 | 389 | https://whatthecommit.com/ 390 | 391 | ## 喜歡它嗎？ 392 | 393 | [說點感謝！](https://saythanks.io/to/RomuloOliveira) 394 | 395 | ## 貢獻 396 | 397 | 感謝任何形式的幫助。例如： 398 | 399 | - 語法和拼寫的糾正 400 | - 翻譯成其他語言 401 | - 原引用的改進 402 | - 不正確或不完整的訊息 403 | 404 | ## 靈感、來源以及補充閱讀 405 | 406 | - [如何寫 Git Commit Message](https://chris.beams.io/posts/git-commit/) 407 | - [Pro Git Book - Commit 指導手冊](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) 408 | - [關於 Git Commit Messages 的說明](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 409 | - [merging 與 rebase](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) 410 | - [Pro Git Book - 修改歷史紀錄](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) 411 | --------------------------------------------------------------------------------