[#26] Document approach to copyright in README

fbiville · Dec 28, 2018 · de79d06 · de79d06
1 parent 0b0c0f7
commit de79d06
Showing 1 changed file with 50 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -7,9 +7,9 @@ It is biased towards Golang but should work on any other language (provided a co
 
 [![Build Status](https://travis-ci.org/fbiville/headache.svg?branch=master)](https://travis-ci.org/fbiville/headache)
 
-## Example
+## Quick start
 
-By default, `headache` looks for a file named `headache.json` in the current directory:
+By default, `headache` looks for a configuration file named `headache.json` in the directory in which it is invoked:
 
 ```json
 {
@@ -23,7 +23,7 @@ By default, `headache` looks for a file named `headache.json` in the current dir
 }
 ```
 
-`license-header.txt`:
+`license-header.txt` (note the absence of `Year` parameter in the configuration file):
 ```
 Copyright {{.Year}} {{.Owner}}
 
@@ -40,26 +40,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ```
 
-
-## Settings
-
-`headache` relies on the emerging [JSON Schema standard](https://json-schema.org/) to validate its configuration.
-`headache` schema is defined [here](https://fbiville.github.io/headache/schema.json).
-
-In layman's terms, here are all the possible settings:
-
-Setting            | Type                    | Definition                                             |
-| ---------------- |:----------------------: | -----------------------------------------------------: |
-| `headerFile`     | string                  | **[required]** Path to the parameterized license header. Parameters are referenced with the following syntax: {{.PARAMETER-NAME}}               |
-| `style`          | string                  | **[required]** One of: `SlashStar` (`/* ... */`), `SlashSlash` (`// ...`) |
-| `includes`       | array of strings        | **[required, min size=1]** File globs to include (`*` and `**` are supported)     |
-| `excludes`       | array of strings        | File globs to exclude (`*` and `**` are supported)     |
-| `data`           | map of string to string | Key-value pairs, matching the parameters used in `headerFile`.<br>Please note that `{{.Year}}` is a reserved parameter and will automatically be computed based on the files versioning information.  |
-
-
-## Run
-
-By default, a file named `headache.json` must be present in the current directory.
+### Run
 
 All you have to do then is:
 ```shell
@@ -70,11 +51,56 @@ All you have to do then is:
 As a result, source files will be changed and `.headache-run` will be generated to keep track of `headache` last execution.
 This file must be versioned along with the source file changes.
 
-## Run with custom configuration
+### Run with custom configuration
 
 Alternatively, the configuration file can be explicitly provided:
 ```shell
  $ go get -u github.com/fbiville/headache
  $ $(GOBIN)/headache --configuration /path/to/configuration.json
 ```
 
+## Reference documentation
+
+### Approach
+
+`headache` approach to copyright is well explained in [this stackoverflow answer](https://stackoverflow.com/a/2391555/277128), 
+read it first!
+
+Now that you read this, here are two important points:
+
+ - Copyright years have to be updated when a significant change occurs.
+
+There is, to the author knowledge, no automatic solution to distinguish a trivial
+change from a significant one.
+
+Based on this premise, `headache` will process all files matching the configuration
+and that have been changed since its last execution.
+`headache` will then compute the copyright year, file by file, from their available versioning information (typically 
+by retrieving the relevant dates from Git commits).
+
+**It is up to the project maintainer to discard the generated changes if they are not relevant.**
+
+ - > The [first] date on the [copyright] notice establishes how far back the claim is made.
+ 
+This claim could predate any commit associated to the file (imagine a file copied from project
+to project for years).
+
+`headache` will never overwrite the start date of the copyright year if it finds one.
+
+### Configuration
+
+`headache` relies on the emerging [JSON Schema standard](https://json-schema.org/) to validate its configuration.
+`headache` schema is defined [here](https://fbiville.github.io/headache/schema.json).
+
+In layman's terms, here are all the possible settings:
+
+Setting            | Type                    | Definition                                             |
+| ---------------- |:----------------------: | -----------------------------------------------------: |
+| `headerFile`     | string                  | **[required]** Path to the parameterized license header. Parameters are referenced with the following syntax: {{.PARAMETER-NAME}}               |
+| `style`          | string                  | **[required]** One of: `SlashStar` (`/* ... */`), `SlashSlash` (`// ...`) |
+| `includes`       | array of strings        | **[required, min size=1]** File globs to include (`*` and `**` are supported)     |
+| `excludes`       | array of strings        | File globs to exclude (`*` and `**` are supported)     |
+| `data`           | map of string to string | Key-value pairs, matching the parameters used in `headerFile`.<br>Please note that `{{.Year}}` is a reserved parameter and will automatically be computed based on the files versioning information.  |
+
+
+