.gitlabels

   1 - (new:<issue>)* indicates new functionality, features, documentation, et cetera are introduced in this commit [optionally includes related issue ID]
   2 - (fix:<issue>)* indicates changes that fix outstanding bugs or problems in some way [optionally includes issue ID]
   3 - (re)* indicates changes that subtly change things for the better, possibly without changing the actual effect of any code (short for ‘refactor’)
   4 # [*]: At least one of these should apply to every commit!
   5
   6 - (-) indicates a relatively minor or unimportant commit, worthy of being ignored by most interested parties
   7
   8 - (api) indicates this commit modifies existing (usually documented) embedder-APIs in some (usually breaking) way, while nominally not affecting the interpreter's functionality
   9    - (vis) aplies to commits that modify the interpreter's functionality, as seen from *within the language* (i.e. affecting libspace) (for ‘visible API’, meaning visible-from-libspace)
  10 # note: (fix), (api), and (new) *change how things operate* from the viewpoint of an API consumer or extension
  11 #       developer (when not combined with a form of (noop)), whereas (re) causes no operational changes (from
  12 #       said point of view), instead improving the overall quality of the code in some way, such as causing it to
  13 #       execute faster or require fewer resources
  14
  15 - (incomplete) indicates a (rare!) commit that applies code that is *known at commit time* to not pass its own tests, or meet its own goals
  16   - (HARM) indicates an (even rarer!) commit that is known (at the time of committing) to *break* the codebase
  17 - (completes:<commit>) indicates that this commit completes the work introduced or begun in another (incomplete) or (HARM) <commit>
  18 # note: it’s *never* safe to check-out and compile code between an (incomplete) (or (harm))
  19 #       commit, and its corresponding (completes:) commit!
  20
  21 - (tests) indicates a commit that does *not* modify any implementation code, in any way (instead, indicates modifying code in the test suite)
  22 - (noop) as (tests), except indicates that a commit does not modify any code belonging to the test suite either. Usually not used, see the below alternatives
  23   - (style) indicates a commit that only changes alignment/spacing/visual orientation of code or documentation
  24   - (doc) indicates commits that change commentary, documentation, etc (exclusive of actual *executed* code)
  25     - (meta) indicates meta-project changes, not applying to the codebase, tests, or documentation
  26
  27
  28
  29 # --- ---- --- -- /!\ -- --- ---- --- #
  30
  31 # What is this?
  32 # =============
  33 # [`.gitlabels`][gh] is a file that defines a series of “labels” that can be applied to [git][] commits.
  34 #
  35 # Each label is intended to “describe” a given commit in a human- and machine-readable way. These can then be used
  36 # to search and filter commit lists, to bring more ‘signal’ out of the changeset ‘noise.’
  37 #
  38 #   [git]: http://git-scm.com/ "Git: *Fast* version-control and source-code management system"
  39 #   [gh]: http://github.com/ELLIOTTCABLE/.gitlabels "The .gitlabels project"
  40 #
  41 # Examples
  42 # --------
  43 # - filtering out typo-fixes and other drudgery by excluding all commits with the `(-)` label
  44 # - gathering a quick summary of the changes *you* need to know about in a new release of your favourite library by
  45 #   searching for commits between the git tags ‘v1.03’ and ‘v1.04’ that include the label `(api)`
  46 # - following the evolution of a particular developer’s personal style by filtering on commits by that developer
  47 #   using both of the `(style refactor)` labels
  48 #
  49 # Usage
  50 # -----
  51 # Applying labels to your project is as simple as these two steps:
  52 #
  53 # ### Add a `.gitlabels` file
  54 # Your file, like this one, should exist in your project’s root directory (just like `.gitignore` and
  55 # `.gitattributes`!), and should consist of lines of the following format:
  56 #
  57 #     - (an-awesome-label:<argument_type>) some description of the label over here, guys!
  58 #
  59 # Labels can be subcategorized under other labels by indenting the `-` preceding the label by two spaces. Filtering
  60 # against a label should theoretically apply to all results that match sublabels as well. Descriptions must be
  61 # entirely on the same line (sorry, guys, no hard-wrapping descriptions if they get long!).
  62 #
  63 # Lines containing only whitespace or beginning with a number sign/hash (`#`) in the *first column* will be
  64 # discarded during parsing, and completely ignored. You may use these to provide commentary and rationale on your
  65 # project’s labeling system, or for any other purpose you desire.
  66 #
  67 # The parenthesis may only contain a single label, that is, they may not contain any of the characters that are not
  68 # legal in label names, other than the colon (`:`) necessary to declare an optional argument and its type. The
  69 # argument declaration (see below) must be surrounded by angle brackets (`<` and `>`).
  70 #
  71 # ### Label your commits
  72 # The fun part! Do what you like, just be *absolutely consistent* about it; if you collaborate with other
  73 # developers on the project, you should also document the labels using comments in `.gitlabels`, your README, or
  74 # some other source, and then encourage your collaborators to apply them as well.
  75 #
  76 # Labels go at the very start of a commit’s commit message in parenthesis, separated by spaces or commas. For
  77 # instance:
  78 #
  79 #     commit e17f638848fb05a43b2cb431fabdbebc84ac091a
  80 #     Author: elliottcable <splat@ell.io>
  81 #     Date:   Sat Feb 26 23:24:29 2011 -0500
  82 #
  83 #       (doc closes:1234 see:b3b2e05 -) I love pretty much anything that comes from pigflesh.
  84 #
  85 # This commit’s labels comprises `(doc)`, `(closes)`, `(see)`, and `(-)`; in this example, perhaps, these could
  86 # mean that this commit comprises an unimportant (in the larger scheme of things) change to some documentation that
  87 # fixes some typos or something. Those typos would have been reported in the project’s issue tracker as issue
  88 # number 1234; the other commit whose ID began with b3b2e05 was somehow relevant as well.
  89 #
  90 # Labels may include a single argument, if described by the `.gitlabels`, which documents a related piece of data.
  91 # These arguments may only be of a limited set of data types (defined by whatever label-parsing system you use, but
  92 # I suggest at least `<commit>` and `<issue>` types of data). These might include a `(closes:<issue>)` or
  93 # `(related:<commit>)` label, for example. Arguments are never “required,” but a given label may not necessarily
  94 # make a lot of sense without its intended payload.
  95 #
  96 # Rationale
  97 # ---------
  98 # The purpose of this system is basically to encourage more *granular* committing—that is, creating more commits
  99 # for fewer changes, and ensuring each commit is more “enclosed.” I believe a project’s git commit-log should be
 100 # sufficient to describe the entire history of the project, *as it was experienced by the developers of the
 101 # project*; that is, allow any given ‘noob’ developer to browse the commit history and learn the same things that
 102 # the creators of the project learned through their work. The mistakes they made, the improvements they invented,
 103 # in a word, the *soul* of the project, should be evidenced by the commit log. “Labels” make this easier, as it’s
 104 # less intimidating to have a commit log with thousands of commits if you know people can ignore those commits that
 105 # are irrelevant to them.
 106 #
 107 # Notes
 108 # -----
 109 # - The open-parenthesis (`(`) indicating the start of a commit’s labels must be the very first byte of a commit
 110 #   message, and there may be no close-parenthesis until the end of all labels
 111 # - The omission of an open-parenthesis (`(`), or the inclusion of an open-parenthesis in the first byte
 112 #   immediately followed by a closing-parenthesis (`()`, possibly with some meaningless whitespace/commas),
 113 #   indicates no labels apply
 114 # - Labels’ names themselves may contain any Unicode character *except*: whitespace, colons (`:`), commas (`,`), or
 115 #   parenthesis (`(` or `)`), as these characters are reserved for parsing label data
 116 # - Labels’ names are case-sensitive; `FOO` is not to be considered the same label as `foo`
 117 # - Descriptions in the `.gitlabels` file are not required, but are suggested; rationale is always a good thing!
 118 # - Not all labels must be included in `.gitlabels`, but labels will not include descriptions, be related (as
 119 #   parents or children) to other labels, or be legally allowed any arguments, if they are not so included
 120 # - Arguments are illegal for a given label unless they are included in `.gitlabels`
 121 # - An argumentative payload may be surrounded by a pair of double quotes (`"`) if it contains anything
 122 #   disallowed in a label’s name, such as whitespace (see above); it may not, under any circumstances, *contain*
 123 #   any double-quote characters
 124 # - The same label may appear multiple times on a single commit, and *may* include different arguments each time.
 125 # - *Any* series of whitespace and/or commas may separate labels (though newlines are inadvisable)
 126 #
 127 # (I, elliottcable, hereby release everything below the line containing “What is this?” into the public domain.
 128 #  Use, distribute, and re-use as you please. Hell, I’d *love* it if you’d spread it around; maybe then, @GitHub
 129 #  would be forced to support label filtering on `/compare/` pages! :D
 130 #
 131 #  I do, however, request that you either retain this explanatory document below the content of your `.gitlabels`
 132 #  file as I do, or include a link to http://github.com/elliottcable/.gitlabels instead. Help spread the word!)