//
// 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 License-Eye 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 txt, 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 license-eye will comment the check results on the pull request, `on-failure`, `always`, `never`. Options other than `never` requre 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]