license-eye/README.adoc - skywalking-eyes - Git at Google

 //
 // Licensed to Apache Software Foundation (ASF) under one or more contributor
 // license agreements. See the NOTICE file distributed with
 // this work for additional information regarding copyright
 // ownership. Apache Software Foundation (ASF) licenses this file to you under
 // the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing,
 // software distributed under the License is distributed on an
 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
 //
 = License-Eye
 :repo: https://github.com/apache/skywalking-eyes
 :name: License-Eye

 A full-featured license guard to check and fix license headers and dependencies' licenses.

 == Usage

 You can use {name} in GitHub Actions or in your local machine.

 === GitHub Actions

 To use {name} in GitHub Actions, add a step in your GitHub workflow.

 [source,yaml]
 ----
 - name: Check License Header
   uses: apache/skywalking-eyes@main      # always prefer to use a revision instead of `main`.
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # needed only when you want License-Eye to comment on the pull request.
 ----

 Add a `.licenserc.yaml` in the root of your project, for Apache Software Foundation projects, the following configuration should be enough.

 [source,yaml]
 ----
 header:
   license:
     spdx-id: Apache-2.0
     copyright-owner: Apache Software Foundation

   paths-ignore:
     - 'dist'
     - 'licenses'
     - '**/*.md'
     - 'LICENSE'
     - 'NOTICE'

   comment: on-failure
 ----

 NOTE: The full configurations can be found in <<Configurations,the configuration section>>.

 === Use as a Binary

 ==== Install

 [subs="attributes",source,bash]
 ----
 $ git clone {repo}
 $ cd skywalking-eyes/license-eye
 $ make build
 ----

 ===== Check License Header

 [source,bash]
 ----
 $ bin/darwin/license-eye -c test/testdata/.licenserc_for_test_fix.yaml header check

 INFO Loading configuration from file: test/testdata/.licenserc_for_test.yaml
 INFO Totally checked 23 files, valid: 8, invalid: 8, ignored: 7, fixed: 0
 ERROR The following files don't have a valid license header:
 test/testdata/include_test/without_license/testcase.go
 test/testdata/include_test/without_license/testcase.graphql
 test/testdata/include_test/without_license/testcase.java
 test/testdata/include_test/without_license/testcase.md
 test/testdata/include_test/without_license/testcase.py
 test/testdata/include_test/without_license/testcase.sh
 test/testdata/include_test/without_license/testcase.yaml
 test/testdata/include_test/without_license/testcase.yml
 exit status 1
 ----

 ==== Fix License Header

 [source,bash]
 ----
 $ bin/darwin/license-eye -c test/testdata/.licenserc_for_test_fix.yaml header fix

 INFO Loading configuration from file: test/testdata/.licenserc_for_test_fix.yaml
 INFO Totally checked 16 files, valid: 7, invalid: 8, ignored: 1, fixed: 8
 ----

 == Configurations

 [source,yaml]
 ----
 header: # <1>
   license:
     spdx-id: Apache-2.0 # <2>
     copyright-owner: Apache Software Foundation # <3>
     content: | # <4>
       Licensed to Apache Software Foundation (ASF) under one or more contributor
       license agreements. See the NOTICE file distributed with
       this work for additional information regarding copyright
       ownership. Apache Software Foundation (ASF) licenses this file to you under
       the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License.
       You may obtain a copy of the License at

           http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing,
       software distributed under the License is distributed on an
       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
       KIND, either express or implied.  See the License for the
       specific language governing permissions and limitations
       under the License.

     pattern: | # <5>
       Licensed to the Apache Software Foundation under one or more contributor
       license agreements. See the NOTICE file distributed with
       this work for additional information regarding copyright
       ownership. The Apache Software Foundation licenses this file to you under
       the Apache License, Version 2.0 \(the "License"\); you may
       not use this file except in compliance with the License.
       You may obtain a copy of the License at

           http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing,
       software distributed under the License is distributed on an
       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
       KIND, either express or implied.  See the License for the
       specific language governing permissions and limitations
       under the License.

   paths: # <6>
     - '**'

   paths-ignore: # <7>
     - 'dist'
     - 'licenses'
     - '**/*.md'
     - '**/testdata/**'
     - '**/go.mod'
     - '**/go.sum'
     - 'LICENSE'
     - 'NOTICE'
     - '**/assets/languages.yaml'
     - '**/assets/assets.gen.go'

   comment: on-failure # <8>
 ----
 <1> `header` section is configurations for source codes license header.
 <2> The link:https://spdx.org/licenses/[SPDX ID] of the license, it's convenient when your license is standard SPDX license, so that you can simply specify this identifier without copying the whole license `content` or `pattern`. This will be used as the content when `fix` command needs to insert a license header.
 <3> The copyright owner to replace the `[owner]` in the `SPDX-ID` license template.
 <4> If you are not using the standard license text, you can paste your license text here, this will be used as the content when `fix` command needs to insert a license header, if both `license` and `SPDX-ID` are specified, `license` wins.
 <5> `pattern` is an optional regexp. You don't need this if all the file headers are the same as `license` or the license of `SPDX-ID`, otherwise you need to compose a pattern that matches your license texts.
 <6> `paths` are the path list that will be checked (and fixed) by license-eye, default is `['++**++']`. Formats like `++**/*.md++` and `++**/bin/**++` are supported.
 <7> `paths-ignore` are the path list that will be ignored by license-eye. By default, `.git` and the content in `.gitignore` will be inflated into the `paths-ignore` list.
 <8> On what condition {name} will comment the check results on the pull request, `on-failure`, `always`, `never`. Options other than `never` require the environment variable `GITHUB_TOKEN` to be set.

 NOTE: When the `SPDX-ID` is Apache-2.0 and the owner is Apache Software foundation, the content would be link:https://www.apache.org/legal/src-headers.html#headers[a dedicated license] link:https://www.apache.org/foundation/license-faq.html#Apply-My-Software[specified by the ASF], otherwise, the license would be link:https://www.apache.org/foundation/license-faq.html#Apply-My-Software[the standard one].

 == Supported File Types

 The `check` command theoretically supports all kinds of file types, while the supported file types of `fix` command can be found link:assets/languages.yaml[in this YAML file].
 In the YAML file, if the language has a non-empty property `comment_style_id`, and the comment style id is declared in link:assets/styles.yaml[the comment styles file], then the language is supported by `fix` command.

 [source,yaml]
 .link:assets/languages.yaml[tags=java]
 ----
 include::assets/languages.yaml[tags=java]
 ----

 [source,yaml]
 .link:assets/styles.yaml[tags=SlashAsterisk]
 ----
 include::assets/styles.yaml[tags=SlashAsterisk]
 ----
 <1> The leading characters of the starting of a block comment.
 <2> The leading characters of the middle lines of a block comment.
 <3> The leading characters of the ending line of a block comment.

 == Contribution

 - If you find any file type should be supported by the aforementioned configurations but is not listed there, feel free to link:https://github.com/apache/skywalking-eyes/pulls[open a pull request] to add the configuration into the 2 files.
 - If you find the license template of an SPDX ID is not supported, feel free to link:https://github.com/apache/skywalking-eyes/pulls[open a pull request] to add it into link:assets/lcs-templates[the template folder].

 == License

 link:https://github.com/apache/skywalking/blob/master/LICENSE[Apache License 2.0]
	//
	// Licensed to Apache Software Foundation (ASF) under one or more contributor
	// license agreements. See the NOTICE file distributed with
	// this work for additional information regarding copyright
	// ownership. Apache Software Foundation (ASF) licenses this file to you under
	// the Apache License, Version 2.0 (the "License"); you may
	// not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.
	//
	= License-Eye
	:repo: https://github.com/apache/skywalking-eyes
	:name: License-Eye

	A full-featured license guard to check and fix license headers and dependencies' licenses.

	== Usage

	You can use {name} in GitHub Actions or in your local machine.

	=== GitHub Actions

	To use {name} in GitHub Actions, add a step in your GitHub workflow.

	[source,yaml]
	----
	- name: Check License Header
	uses: apache/skywalking-eyes@main # always prefer to use a revision instead of `main`.
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # needed only when you want License-Eye to comment on the pull request.
	----

	Add a `.licenserc.yaml` in the root of your project, for Apache Software Foundation projects, the following configuration should be enough.

	[source,yaml]
	----
	header:
	license:
	spdx-id: Apache-2.0
	copyright-owner: Apache Software Foundation

	paths-ignore:
	- 'dist'
	- 'licenses'
	- '*/.md'
	- 'LICENSE'
	- 'NOTICE'

	comment: on-failure
	----

	NOTE: The full configurations can be found in <<Configurations,the configuration section>>.

	=== Use as a Binary

	==== Install

	[subs="attributes",source,bash]
	----
	$ git clone {repo}
	$ cd skywalking-eyes/license-eye
	$ make build
	----

	===== Check License Header

	[source,bash]
	----
	$ bin/darwin/license-eye -c test/testdata/.licenserc_for_test_fix.yaml header check

	INFO Loading configuration from file: test/testdata/.licenserc_for_test.yaml
	INFO Totally checked 23 files, valid: 8, invalid: 8, ignored: 7, fixed: 0
	ERROR The following files don't have a valid license header:
	test/testdata/include_test/without_license/testcase.go
	test/testdata/include_test/without_license/testcase.graphql
	test/testdata/include_test/without_license/testcase.java
	test/testdata/include_test/without_license/testcase.md
	test/testdata/include_test/without_license/testcase.py
	test/testdata/include_test/without_license/testcase.sh
	test/testdata/include_test/without_license/testcase.yaml
	test/testdata/include_test/without_license/testcase.yml
	exit status 1
	----

	==== Fix License Header

	[source,bash]
	----
	$ bin/darwin/license-eye -c test/testdata/.licenserc_for_test_fix.yaml header fix

	INFO Loading configuration from file: test/testdata/.licenserc_for_test_fix.yaml
	INFO Totally checked 16 files, valid: 7, invalid: 8, ignored: 1, fixed: 8
	----

	== Configurations

	[source,yaml]
	----
	header: # <1>
	license:
	spdx-id: Apache-2.0 # <2>
	copyright-owner: Apache Software Foundation # <3>
	content: \| # <4>
	Licensed to Apache Software Foundation (ASF) under one or more contributor
	license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright
	ownership. Apache Software Foundation (ASF) licenses this file to you under
	the Apache License, Version 2.0 (the "License"); you may
	not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.

	pattern: \| # <5>
	Licensed to the Apache Software Foundation under one or more contributor
	license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright
	ownership. The Apache Software Foundation licenses this file to you under
	the Apache License, Version 2.0 \(the "License"\); you may
	not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.

	paths: # <6>
	- '**'

	paths-ignore: # <7>
	- 'dist'
	- 'licenses'
	- '*/.md'
	- '/testdata/'
	- '**/go.mod'
	- '**/go.sum'
	- 'LICENSE'
	- 'NOTICE'
	- '**/assets/languages.yaml'
	- '**/assets/assets.gen.go'

	comment: on-failure # <8>
	----
	<1> `header` section is configurations for source codes license header.
	<2> The link:https://spdx.org/licenses/[SPDX ID] of the license, it's convenient when your license is standard SPDX license, so that you can simply specify this identifier without copying the whole license `content` or `pattern`. This will be used as the content when `fix` command needs to insert a license header.
	<3> The copyright owner to replace the `[owner]` in the `SPDX-ID` license template.
	<4> If you are not using the standard license text, you can paste your license text here, this will be used as the content when `fix` command needs to insert a license header, if both `license` and `SPDX-ID` are specified, `license` wins.
	<5> `pattern` is an optional regexp. You don't need this if all the file headers are the same as `license` or the license of `SPDX-ID`, otherwise you need to compose a pattern that matches your license texts.
	<6> `paths` are the path list that will be checked (and fixed) by license-eye, default is `['++++']`. Formats like `++/.md++` and `++/bin/*++` are supported.
	<7> `paths-ignore` are the path list that will be ignored by license-eye. By default, `.git` and the content in `.gitignore` will be inflated into the `paths-ignore` list.
	<8> On what condition {name} will comment the check results on the pull request, `on-failure`, `always`, `never`. Options other than `never` require the environment variable `GITHUB_TOKEN` to be set.

	NOTE: When the `SPDX-ID` is Apache-2.0 and the owner is Apache Software foundation, the content would be link:https://www.apache.org/legal/src-headers.html#headers[a dedicated license] link:https://www.apache.org/foundation/license-faq.html#Apply-My-Software[specified by the ASF], otherwise, the license would be link:https://www.apache.org/foundation/license-faq.html#Apply-My-Software[the standard one].

	== Supported File Types

	The `check` command theoretically supports all kinds of file types, while the supported file types of `fix` command can be found link:assets/languages.yaml[in this YAML file].
	In the YAML file, if the language has a non-empty property `comment_style_id`, and the comment style id is declared in link:assets/styles.yaml[the comment styles file], then the language is supported by `fix` command.

	[source,yaml]
	.link:assets/languages.yaml[tags=java]
	----
	include::assets/languages.yaml[tags=java]
	----

	[source,yaml]
	.link:assets/styles.yaml[tags=SlashAsterisk]
	----
	include::assets/styles.yaml[tags=SlashAsterisk]
	----
	<1> The leading characters of the starting of a block comment.
	<2> The leading characters of the middle lines of a block comment.
	<3> The leading characters of the ending line of a block comment.

	== Contribution

	- If you find any file type should be supported by the aforementioned configurations but is not listed there, feel free to link:https://github.com/apache/skywalking-eyes/pulls[open a pull request] to add the configuration into the 2 files.
	- If you find the license template of an SPDX ID is not supported, feel free to link:https://github.com/apache/skywalking-eyes/pulls[open a pull request] to add it into link:assets/lcs-templates[the template folder].

	== License

	link:https://github.com/apache/skywalking/blob/master/LICENSE[Apache License 2.0]