diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 61 |
1 files changed, 37 insertions, 24 deletions
@@ -54,7 +54,7 @@ copyright as stated. User then can repeat edit "spdxconv.cfg", "scan" and "apply" command multiple times, until they satisfied with the result. -## init command +### init command The first thing to do is to generate the configuration file using @@ -139,7 +139,7 @@ For quick references here are several rules that you need to be aware of, The next subsection explain the content of configuration file and how it affect the program during scan and apply. -### default section +#### default section This section define the default license identifier, year, and copyright text to be inserted into file if no `match-license` or `match-copyright` found in @@ -157,7 +157,7 @@ example, "2000-2026"), or list of year with comma separated (for example, The `file_copyright_text` set the default author and contact in `SPDX-FileCopyrightText`. -For example, "John Doe <john.doe@example>". +For example, "John Doe \<john.doe@example\>". You should fill the `license_identifier`, `copyright_year`, and `file_copyright_text` before continue running the program. @@ -183,7 +183,10 @@ That means, if the file name match, it will create new file with ".license" suffix that contains SPDX identifiers only, instead of inserting to the file directly. -### match-license section +If the file name does not match with one of the "match-file-pattern" then +the file will be flagged as "unknown". + +#### match-license section <!-- REUSE-IgnoreStart --> @@ -195,7 +198,7 @@ line that match with "SPDX-License-Identifier:". If there is a match, at the top or bottom, the scan will stop and continue for processing copyright. -If there is no match it will search for a line that match with "pattern" +If no match it will search for a line that match with "pattern" regular expression. If there is a line that match with it, the value in "match-license::license_identifier" will replace the @@ -206,7 +209,7 @@ search for the pattern before and after the matched line and delete it. The "delete_line_before" and "delete_line_after" can be defined zero or multiple times. -### match-copyright section +#### match-copyright section The match-copyright section define the pattern to match with old copyright text. @@ -218,30 +221,30 @@ the date of the first commit in history of the file using the Source Code Management (SCM). In git SCM, it will run "git log --follow file". -Example, given the following old copyright text, +For example, given the following old copyright text, ``` -Copyright 2022, John Doe <john.doe@email>. All rights reserved. +// Copyright 2022, John Doe <john.doe@email>. All rights reserved. ``` we can capture the year, author, and contact using the following regex, ``` -^(//+|#+|/\\*+|<!--+)?\\s*Copyright\\s+(?<year>\\d{4}),?\\s+(?<author>.*)\\s+<(?<contact>.*)>.*$" +^//+\\s*Copyright\\s+(?<year>\\d{4}),?\\s+(?<author>.*)\\s+<(?<contact>.*)>.*$" ``` The `match-copyright` section can also contains zero or more -`delete_line_before` and `delete_line_after` pattern. +`delete_line_before` and `delete_line_after` patterns. The `delete_line_before` delete lines before matched line pattern, and `delete_line_after` contains regex to delete lines after matched line pattern. -## scan command +### scan command The scan command scan the files that need to be converted or inserted with SPDX identifiers in the current directory. The result of scan is stored inside a report file named "spdxconv.report". -There are no other files modified after scan completed. +There are no other files modified during and after scan completed. User then can inspect and modify the report to exclude certain files or changes the behaviour of apply command. @@ -256,15 +259,21 @@ configuration. (1) Check the file for SPDX-License-Identifier and SPDX-FileCopyrightText. If both exist, skip the file. -(2) For each match-license in the configuration, +(2) If SPDX-License-Identifier line not exist, find the old license using +the match-license sections. + +For each match-license in the configuration, (2.1) If there is a match, record it as "match" and its line number into the report. (2.2) If no match, use the default license from configuration, record it as -"default" with 0 line number in the report. +"default" with "0" as line number in the report. + +(3) If SPDX-FileCopyrightText line not exist, find the old copyright text +using the match-copyright sections. -(3) For each match-copyright in the configuration, +For each match-copyright in the configuration, (3.1) If there is a match, get the year, author, and contact; and record it as "match" and its line number into the report. @@ -275,9 +284,9 @@ If no commit history or its not using git, use default copyright year from configuration. (3.2) If there is no match, use default copyright year and text from -configuration, and record as "default" in the report. +configuration, and record it as "default" in the report. -### spdxconv.report file format +#### spdxconv.report file format Each line in the report file is formatted using CSV and has several columns separated by comma, @@ -295,8 +304,10 @@ path = { unicode_char } license_id = "default" | "exist" | "match" idx_license_id = 1 * decimal_digit -year = 4 * decimal_digit ("," year) - | 4 * decimal_digit "-" 4*decimal_digit +year = single_year { "," single_year } + | single_year "-" single_year + +single_year = 4 * decimal_digit copyright_id = "default" | "exist" | "match" idx_copyright_id = 1 * decimal_digit @@ -306,11 +317,12 @@ The `path` column define the path to the file that will be processed by `apply` command. The `license_id` column define the license identifier to be used. -The value either, +The value is either, - default - insert new identifier and using the default license_identifier value from configuration. -- exist - the SPDX-License-Identifier already exist in file. +- exist - the SPDX-License-Identifier already exist in file, at line number + set in `idx_license_id` - match - one of the pattern in match-license found in file at line number set in `idx_license_id`. @@ -331,7 +343,8 @@ The value is either, - default - insert new identifier using the default copyright_text value from configuration. -- exist - the SPDX-FileCopyrightText already exist in file. +- exist - the SPDX-FileCopyrightText already exist in file, at line number + set in `idx_copyright_id`. - match - one of the pattern in the match-copyright found in file at line number set in `idx_copyright_id`. @@ -343,7 +356,7 @@ found at the bottom. The `comment_prefix` and `comment_suffix` contains the prefix and suffix used as comment in the file. -### spdxconv.report file groups +#### spdxconv.report file groups Each file in the report file is collected into three groups: regular, binary, and unknown files. @@ -376,7 +389,7 @@ to be used. This files will not be processed, it is listed here so user can inspect, modify the configuration, and rerun the scan command for the next cycle. -## apply command +### apply command The apply command read the "spdxconv.report" and apply the license and copyright in the file as stated on each line in the report. |