Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

(new meta) Adding a .gitlabels file.

This documents my “labels” system for managing commit metadata. More information: http://github.com/elliottcable/.gitlabels
  • Loading branch information...
commit 949e0c5d9ce9f910a18ff5356f7f1ad238f1731f 1 parent 57cf7f9
authored February 27, 2011

Showing 1 changed file with 129 additions and 0 deletions. Show diff stats Hide diff stats

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

0 notes on commit 949e0c5

Please sign in to comment.
Something went wrong with that request. Please try again.