diff options
Diffstat (limited to 'site/code/commit-messages/index.html')
| -rw-r--r-- | site/code/commit-messages/index.html | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/site/code/commit-messages/index.html b/site/code/commit-messages/index.html new file mode 100644 index 0000000..2692dc0 --- /dev/null +++ b/site/code/commit-messages/index.html @@ -0,0 +1,177 @@ +<!DOCTYPE html> +<html lang="en"> + <head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + + + + <link rel="shortcut icon" href="../../img/favicon.ico"> + <title>Writing Good Commit Messages - The Grimoire</title> + <link href="../../css/bootstrap-custom.min.css" rel="stylesheet"> + <link href="../../css/font-awesome.min.css" rel="stylesheet"> + <link href="../../css/base.css" rel="stylesheet"> + <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css"> + <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script> + <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script> + <![endif]--> + + <script src="../../js/jquery-1.10.2.min.js" defer></script> + <script src="../../js/bootstrap-3.0.3.min.js" defer></script> + <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script> + <script>hljs.initHighlightingOnLoad();</script> + </head> + + <body> + + <div class="navbar navbar-default navbar-fixed-top" role="navigation"> + <div class="container"> + + <!-- Collapsed navigation --> + <div class="navbar-header"> + <!-- Expander button --> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="../..">The Grimoire</a> + </div> + + <!-- Expanded navigation --> + <div class="navbar-collapse collapse"> + <!-- Main navigation --> + <ul class="nav navbar-nav"> + <li > + <a href="../..">Owen Jacobson</a> + </li> + <li > + <a href="../">Code</a> + </li> + <li > + <a href="../../nomic/">Nomic</a> + </li> + </ul> + + <ul class="nav navbar-nav navbar-right"> + <li> + <a href="#" data-toggle="modal" data-target="#mkdocs_search_modal"> + <i class="fa fa-search"></i> Search + </a> + </li> + <li> + <a href="https://github.com/grimoire-ca/bliki/edit/master/docs/code/commit-messages.md"><i class="fa fa-github"></i> Edit on GitHub</a> + </li> + </ul> + </div> + </div> + </div> + + <div class="container"> + <div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary"> + <ul class="nav bs-sidenav"> + <li class="main active"><a href="#writing-good-commit-messages">Writing Good Commit Messages</a></li> + </ul> +</div></div> + <div class="col-md-9" role="main"> + +<h1 id="writing-good-commit-messages">Writing Good Commit Messages<a class="headerlink" href="#writing-good-commit-messages" title="Permanent link">¶</a></h1> +<p>Rule zero: “good” is defined by the standards of the project you're on. Have a look at what the existing messages look like, and try to emulate that first before doing anything else.</p> +<p>Having said that, here are some principles I've found helpful and broadly applicable.</p> +<ul> +<li> +<p>Treat the first line of the message as a one-sentence summary. Most SCM systems have an “overview” command that shows shortened commit messages in bulk, so making the very beginning of the message meaningful helps make those modes more useful for finding specific commits. <em>It's okay for this to be a “what” description</em> if the rest of the message is a “why” description.</p> +</li> +<li> +<p>Fill out the rest of the message with prose outlining why you made the change. Don't reiterate the contents of the change in great detail if you can avoid it: anyone who needs that can read the diff themselves, or reach out to ask for help understanding the change. A good rationale sets context for the problem being solved and addresses the ways the proposed change alters that context.</p> +</li> +<li> +<p>If you use an issue tracker (and you should), include whatever issue-linking notes it supports right at the start of the message, where it'll be visible even in summarized commit logs. If your tracker has absurdly long issue-linking syntax, or doesn't support issue links in commits at all, include a short issue identifier at the front of the message and put the long part somewhere out of the way, such as on a line of its own at the end of the message.</p> +</li> +<li> +<p>If you need rich commit messages (links, lists, and so on), pick one markup language and stick with it. It'll be easier to write useful commit formatters if you only have to deal with one syntax, rather than four. Personally, I use Markdown when I can, or a reduced subset of Markdown, as it's something most developers I interact with will be at least passing familiar with.</p> +</li> +</ul></div> + </div> + + <footer class="col-md-12"> + <hr> + <p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p> + </footer> + <script> + var base_url = "../..", + shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83}; + </script> + <script src="../../js/base.js" defer></script> + <script src="../../search/main.js" defer></script> + + <div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="Search Modal" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">×</span><span class="sr-only">Close</span></button> + <h4 class="modal-title" id="exampleModalLabel">Search</h4> + </div> + <div class="modal-body"> + <p> + From here you can search these documents. Enter + your search terms below. + </p> + <form role="form"> + <div class="form-group"> + <input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here"> + </div> + </form> + <div id="mkdocs-search-results"></div> + </div> + <div class="modal-footer"> + </div> + </div> + </div> +</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="Keyboard Shortcuts Modal" aria-hidden="true"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">×</span><span class="sr-only">Close</span></button> + <h4 class="modal-title" id="exampleModalLabel">Keyboard Shortcuts</h4> + </div> + <div class="modal-body"> + <table class="table"> + <thead> + <tr> + <th style="width: 20%;">Keys</th> + <th>Action</th> + </tr> + </thead> + <tbody> + <tr> + <td class="help shortcut"><kbd>?</kbd></td> + <td>Open this help</td> + </tr> + <tr> + <td class="next shortcut"><kbd>n</kbd></td> + <td>Next page</td> + </tr> + <tr> + <td class="prev shortcut"><kbd>p</kbd></td> + <td>Previous page</td> + </tr> + <tr> + <td class="search shortcut"><kbd>s</kbd></td> + <td>Search</td> + </tr> + </tbody> + </table> + </div> + <div class="modal-footer"> + </div> + </div> + </div> +</div> + + </body> +</html> |