From de79d06a9cb1f1860531e22057e9a67ce8f0c05e Mon Sep 17 00:00:00 2001 From: Florent Biville Date: Fri, 28 Dec 2018 17:55:30 +0100 Subject: [PATCH] [#26] Document approach to copyright in README --- README.md | 74 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 50 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index ca3d794..dcd66e8 100644 --- 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`.
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,7 +51,7 @@ 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 @@ -78,3 +59,48 @@ Alternatively, the configuration file can be explicitly provided: $ $(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`.
Please note that `{{.Year}}` is a reserved parameter and will automatically be computed based on the files versioning information. | + + +