.gitchangelog.rc 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191
  1. ## gitchangelog.rc
  2. ## ---------------
  3. ##
  4. ## This file is a configuration for gitchangelog, found here:
  5. ##
  6. ## https://github.com/vaab/gitchangelog
  7. ##
  8. ## This is a tool for generating changelogs from the output of a git log
  9. ## statement. This configuration file controls how the config file is
  10. ## generated.
  11. ##
  12. ## Expected Commit Message Format
  13. ## ------------------------------
  14. ##
  15. ## ===============================
  16. ## [tag?] [commit message subject]
  17. ##
  18. ## <commit message body text?>
  19. ## * [changelog information]
  20. ## <commit message body text>
  21. ## ===============================
  22. ##
  23. ## In the above example, [tag] is optional and one of:
  24. ##
  25. ## * brk: for breaking changes
  26. ## * new: for new features
  27. ## * bug: for bug fixes
  28. ## * ref: for refactors
  29. ##
  30. ## The bracketed text in the tag is optional. Tags should be applied to indicate
  31. ## that a commit should appear in the changelog, and should reflect which section
  32. ## of the changelog the commit should appear under.
  33. ##
  34. ## If a tag is present, the [commit message subject] will appear as a bullet
  35. ## point in the resulting changelog, in the section indicated by [tag]. This
  36. ## should summarize the change.
  37. ##
  38. ## In many (maybe most) cases, more information is required to describe a change
  39. ## than will fit in a commit subject. This should be included in the body of the
  40. ## commit message, as indicated by [changelog information] above. These lines
  41. ## must start with an astrisk followed by a single whitespace (* ) with any amount
  42. ## of whitespace before the astrisk. All levels of indentation will be collapsed
  43. ## into subbullets of the [commit message subject] bullet point.
  44. ##
  45. ## Example Commit Message
  46. ## ----------------------
  47. ##
  48. ## ===================================================
  49. ## new: adds a cool new feature
  50. ##
  51. ## ABC-123 #done
  52. ##
  53. ## * Adds GET /cool/feature endpoint
  54. ## * Represents a collection of cool features
  55. ## ===================================================
  56. ##
  57. ## Example Output
  58. ## --------------
  59. ##
  60. ## Features:
  61. ##
  62. ## * Adds a cool new feature
  63. ## * Adds GET /cool/feature
  64. ## * Represents a collection of cool features
  65. ##
  66. ## Generating a Changelog
  67. ## ----------------------
  68. ##
  69. ## To generate a changelog for all commits, simply run gitchangelog:
  70. ##
  71. ## gitchangelog
  72. ##
  73. ## To generate a changelog to a specific tag, run gitchangelog like so:
  74. ##
  75. ## gitchangelog ...<tag>
  76. ##
  77. ## To generate a changelog between two tags, run gitchangelog like so:
  78. ##
  79. ## gitchangelog <tag-1>...<tag-2>
  80. ##
  81. ## All of these will output the changelog to the terminal.
  82. ##
  83. ## About This File
  84. ## ---------------
  85. ##
  86. ## This configuration file should live at the root of the project using it, and
  87. ## despite its (required) filename, is a python script that is called by the
  88. ## gitchangelog program to grab settings and functions used to generate the
  89. ## changelog. This file depends on .gitchangelog.tpl, which must live alongside
  90. ## it, and is expected to be a mustache template file controlling how the
  91. ## changelog is outputted. This file _should_ be tracked by git.
  92. import re
  93. from itertools import filterfalse
  94. ## Section Regexps
  95. ##
  96. ## This defines what is looked for in the subject of a commit to decide where,
  97. ## if anywhere, the commit is added to the changelog.
  98. ##
  99. ## This setup defines the follow groups:
  100. ## * Breaking - subject starts with brk:
  101. ## * Features - subject starts with new:
  102. ## * Refactors - subject starts with ref:
  103. ## * Bugfixes - subject starts with bug:
  104. section_regexps = [
  105. ('Added', [
  106. r'^add:',
  107. ]),
  108. ('Removed', [
  109. r'^rm:'
  110. ]),
  111. ('Changed', [
  112. r'^chg:'
  113. ]),
  114. ('Fixed', [
  115. r'^fix:'
  116. ]),
  117. ]
  118. ## Body Processing
  119. ##
  120. ## Commit message bodies are mostly ignored, but if you want bullet points nested
  121. ## under your commit message subject, include them like so:
  122. ##
  123. ## * This will appear under the title
  124. ##
  125. ## These should be used to add specific details about what you changed, if the
  126. ## change was big enough that the single-line message can't convey it all
  127. ## adequately. Don't be shy with these - details are important.
  128. @TextProc
  129. def only_bullets(s):
  130. """
  131. Given the commit body, removes any lines that don't match vaguely this
  132. format:
  133. * Does a thing
  134. For example, if given a commit message like this:
  135. new: Adds support for something
  136. This is for https://jira.linode.com/browser/ARB-123
  137. * Adds GET /some/thing
  138. * Adds GET /some/thing/:id
  139. this will return:
  140. * Adds GET /some/thing
  141. * Adds GET /some/thing/:id
  142. """
  143. lines = s.split('\n')
  144. lines = filterfalse(
  145. lambda c: not re.search(r'^ *\* ', c),
  146. lines
  147. )
  148. lines = [l.split('*', 1)[1].strip() for l in lines if l]
  149. lines = '\n * '.join(lines)
  150. if lines:
  151. lines = ' * '+lines
  152. return lines
  153. body_process = only_bullets
  154. ## Subject Processing
  155. ##
  156. ## Commit message subjects are left wholly intact, except that the grouping tag
  157. ## is removed (since it is used as metadata) and the first word is capitalized.
  158. ## A commit message subject like this:
  159. ##
  160. ## ref moved permissions logic into user object
  161. ##
  162. ## becomes this instead:
  163. ##
  164. ## Moved permissions logic into user object
  165. ##
  166. ## That message will appear in the "Refacotrs" group, preserving the original
  167. ## intention of the tag.
  168. @TextProc
  169. def strip_flag(s):
  170. """
  171. This function is used to strip the flag from the commit summary before adding
  172. it to the changelog. All commits summaries considered will have a tag if
  173. they matched the section regexes, so we will assume that the first word can
  174. be removed.
  175. """
  176. return ' '.join(s.split(' ')[1:])
  177. subject_process = strip_flag | ucfirst
  178. output_engine = mustache(".gitchangelog.tpl")