diff --git a/docs/source/aboutcode-toolkit/home.rst b/docs/source/aboutcode-toolkit/home.rst new file mode 100644 index 00000000..51292e19 --- /dev/null +++ b/docs/source/aboutcode-toolkit/home.rst @@ -0,0 +1,125 @@ +AboutCode Toolkit +================= + +Build and tests status +---------------------- + ++-------+-----------------+--------------+ +|Branch | **Linux/macOS** | **Windows** | ++=======+=================+==============+ +|Master | |master-posix| | |master-win| | ++-------+-----------------+--------------+ +|Develop| |devel-posix| | |devel-win| | ++-------+-----------------+--------------+ + + +The AboutCode Toolkit and ABOUT files provide a simple way to document the +origin, license, usage and other important or interesting information about +third-party software components that you use in your project. + +You start by storing ABOUT files (a small YAML formatted text file with field/value pairs) +side-by-side with each of the third-party software components you use. +Each ABOUT file documents origin and license for one software. +For more information on the ABOUT file format, visit http://www.dejacode.org +There are many examples of ABOUT files (valid or invalid) in the testdata/ +directory of the whole repository. + +The current version of the AboutCode Toolkit can read these ABOUT files so that you +can collect and validate the inventory of third-party components that you use. + +In addition, this tool is able to generate attribution notices and +identify redistributable source code used in your project to help you comply +with open source licenses conditions. + +This version of the AboutCode Toolkit follows the ABOUT specification version 3.0 at: +https://github.com/nexB/aboutcode-toolkit/blob/develop/SPECIFICATION.rst + + +REQUIREMENTS +------------ +The AboutCode Toolkit is tested with Python 2.7 and 3.6 on Linux, Mac and Windows. +You will need to install a Python interpreter if you do not have one already +installed. + +On Linux and Mac, Python is typically pre-installed. To verify which +version may be pre-installed, open a terminal and type: + + python --version + +On Windows or Mac, you can download the latest Python here: + https://www.python.org/downloads/ + +Download the .msi installer for Windows or the .dmg archive for Mac. +Open and run the installer using all the default options. + + +INSTALLATION +------------ +Checkout or download and extract the AboutCode Toolkit from: + https://github.com/nexB/aboutcode-toolkit/ + +To install all the needed dependencies in a virtualenv, run (on posix): + source configure +or on windows: + configure + + +REFERENCE +--------- +See https://github.com/nexB/aboutcode-toolkit/blob/master/REFERENCE.rst for reference +on aboutcode-toolkit usage. + + +TESTS and DEVELOPMENT +--------------------- +To install all the needed development dependencies, run (on posix): + source configure etc/conf/dev +or on windows: + configure etc/conf/dev + +To verify that everything works fine you can run the test suite with: + py.test + + +HELP and SUPPORT +---------------- +If you have a question or find a bug, enter a ticket at: + + https://github.com/nexB/aboutcode-toolkit + +For issues, you can use: + + https://github.com/nexB/aboutcode-toolkit/issues + + +SOURCE CODE +----------- +The AboutCode Toolkit is available through GitHub. For the latest version visit: + https://github.com/nexB/aboutcode-toolkit + + +HACKING +------- +We accept pull requests provided under the same license as this tool. +You agree to the http://developercertificate.org/ + + +LICENSE +------- +The AboutCode Toolkit is released under the Apache 2.0 license. +See (of course) the about.ABOUT file for details. + + +.. |master-posix| image:: https://api.travis-ci.org/nexB/aboutcode-toolkit.png?branch=master + :target: https://travis-ci.org/nexB/aboutcode-toolkit + :alt: Linux Master branch tests status +.. |devel-posix| image:: https://api.travis-ci.org/nexB/aboutcode-toolkit.png?branch=develop + :target: https://travis-ci.org/nexB/aboutcode-toolkit + :alt: Linux Develop branch tests status + +.. |master-win| image:: https://ci.appveyor.com/api/projects/status/uwj2gh8i9ga1mqwn/branch/master?png=true + :target: https://ci.appveyor.com/project/nexB/aboutcode-toolkit + :alt: Windows Master branch tests status +.. |devel-win| image:: https://ci.appveyor.com/api/projects/status/uwj2gh8i9ga1mqwn/branch/develop?png=true + :target: https://ci.appveyor.com/project/nexB/aboutcode-toolkit + :alt: Windows Develop branch tests status diff --git a/docs/source/aboutcode-toolkit/index.rst b/docs/source/aboutcode-toolkit/index.rst new file mode 100644 index 00000000..20a7f03c --- /dev/null +++ b/docs/source/aboutcode-toolkit/index.rst @@ -0,0 +1,9 @@ +**AboutCode-Toolkit Documentation** +=================================== + +.. toctree:: + :maxdepth: 2 + + home + reference + specification \ No newline at end of file diff --git a/docs/source/aboutcode-toolkit/reference.rst b/docs/source/aboutcode-toolkit/reference.rst new file mode 100644 index 00000000..e8777f3e --- /dev/null +++ b/docs/source/aboutcode-toolkit/reference.rst @@ -0,0 +1,357 @@ +Reference +========= + +about +----- + +**Syntax** + +:: + + about [OPTIONS] [COMMANDS] + +**Options:** + +:: + + --version Show the version and exit. + --help Show this message and exit. + +**Commands:** + +:: + + attrib LOCATION: directory, OUTPUT: output file + check LOCATION: directory + gen LOCATION: input file, OUTPUT: directory + inventory LOCATION: directory, OUTPUT: csv file + + +attrib +------ + +**Syntax** + +:: + + about attrib [OPTIONS] LOCATION OUTPUT + + LOCATION: Path to an ABOUT file or a directory containing ABOUT files. + OUTPUT: Path to output file to write the attribution to. + +**Options:** + +:: + + --inventory PATH Path to an inventory file. + --mapping Use for mapping between the input keys and the ABOUT field. + names - mapping.config + --mapping-file Use a custom mapping file with mapping between input + keys and ABOUT field names. + --template PATH Path to a custom attribution template. + --vartext TEXT Variable texts to the attribution template + --verbose Show all the errors and warning. + -q, --quiet Do not print any error/warning. + -h, --help Show this message and exit. + +Purpose +^^^^^^^ +Generate an attribution file which contains the all license information +from the LOCATION along with the license text. + +Assume the following: + +:: + + '/home/about_files/'** contains all the ABOUT files [LOCATION] + '/home/attribution/attribution.html' is the user's output path [OUTPUT] + '/home/project/component_list.csv' is the inventory that user want to be generated + +:: + + $ about attrib /home/about_files/ /home/attribution/attribution.html + +Options +^^^^^^^ + +:: + + --inventory + + This option allows you to define which ABOUT files should be used for attribution generation. + For instance, + '/home/project/component_list.csv' is the inventory that user want to be generated + + $ about attrib --inventory /home/project/component_list.csv LOCATION OUTPUT + + --mapping + + See mapping.config for details + + --mapping-file + + Same behavior as `--mapping` but with custom mapping file + + $ about attrib --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT + + --template + + This option allows you to use your own template for attribution generation. + For instance, if you have a custom template located at: + /home/custom_template/template.html + + $ about attrib --template /home/custom_template/template.html LOCATION OUTPUT + + --vartext + + This option allow you to pass variable texts to the attribution template + + $ about attrib --vartext "title=Attribution Notice" --vartext "header=Product 101" LOCATION OUTPUT + + Users can use the following in the template to get the vartext: + {{ vartext_dict['title'] }} + {{ vartext_dict['header'] }} + + --verbose + + This option tells the tool to show all errors found. + The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING' + + +The following data are passed to jinja2 and, therefore, can be used for a custom template: + * about object: the about objects + * common_licenses: a common license keys list in licenses.py + * license_key_and_context: a dictionary list with license_key as a key and license text as the value + * license_file_name_and_key: a dictionary list with license file name as a key and license key as the value + * license_key_to_license_name: a dictionary list with license key as a key and license file name as the value + + +check +----- + +**Syntax** + +:: + + about check [OPTIONS] LOCATION + + LOCATION: Path to an ABOUT file or a directory with ABOUT files. + +**Options:** + +:: + + --verbose Show all the errors and warning + -h, --help Show this message and exit. + +Purpose +^^^^^^^ +Validating ABOUT files at LOCATION. + +Options +^^^^^^^ + +:: + + --verbose + + This option tells the tool to show all errors found. + The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING' + + $ about check --verbose /home/project/about_files/ + + +gen +--- + +**Syntax** + +:: + + about gen [OPTIONS] LOCATION OUTPUT + + LOCATION: Path to a JSON or CSV inventory file. + OUTPUT: Path to a directory where ABOUT files are generated. + +**Options:** + +:: + + --fetch-license KEY Fetch licenses text from a DejaCode API. and + create .LICENSE side-by-side + with the generated .ABOUT file using data + fetched from a DejaCode License Library. The + following additional options are required: + + api_url - URL to the DejaCode License Library + API endpoint + + api_key - DejaCode API key + Example syntax: + + about gen --fetch-license 'api_url' 'api_key' + --license-notice-text-location PATH Copy the 'license_file' from the directory to + the generated location. + --mapping Use for mapping between the input keys and + the ABOUT field names - mapping.config + --mapping-file Use a custom mapping file with mapping between input + keys and ABOUT field names. + --verbose Show all the errors and warning. + -q, --quiet Do not print any error/warning. + -h, --help Show this message and exit. + +Purpose +^^^^^^^ +Given an inventory of ABOUT files at location, generate ABOUT files in base directory. + +Options +^^^^^^^ + +:: + + --fetch-license + + Fetch licenses text from a DejaCode API. and create .LICENSE side-by-side + with the generated .ABOUT file using data fetched from a DejaCode License Library. + + This option requires 2 parameters: + api_url - URL to the DJE License Library + api_key - Hash key to authenticate yourself in the API. + + In addition, the input needs to have the 'license_expression' field. + (Please contact nexB to get the api_* value to use for this feature) + + $ about gen --fetch-license 'api_url' 'api_key' LOCATION OUTPUT + + --license-notice-text-location + + Copy the license files and notice files to the generated location based on the + 'license_file' and 'notice_file' value in the input from the directory + + For instance, + the directory, /home/licenses_notices/, contains all the licenses and notices that you want: + /home/license/apache2.LICENSE + /home/license/jquery.js.NOTICE + + $ about gen --license-notice-text-location /home/licenses_notices/ LOCATION OUTPUT + + --mapping + + See mapping.config for details + + --mapping-file + + Same behavior as `--mapping` but with custom mapping file + + $ about attrib --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT + + --verbose + + This option tells the tool to show all errors found. + The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING' + + +inventory +--------- + +**Syntax** + +:: + + about inventory [OPTIONS] LOCATION OUTPUT + + LOCATION: Path to an ABOUT file or a directory with ABOUT files. + OUTPUT: Path to the JSON or CSV inventory file to create. + +**Options:** + +:: + + --filter TEXT Filter for the output inventory. + -f, --format [json|csv] Set OUTPUT file format. [default: csv] + --mapping Use file mapping.config to collect the defined not supported fields in ABOUT files. + --mapping-file Use a custom mapping file with mapping between input + keys and ABOUT field names. + --mapping-output FILE Use a custom mapping file with mapping between + ABOUT field names and output keys + --verbose Show all the errors and warning. + -q, --quiet Do not print any error/warning. + -h, --help Show this message and exit. + +Purpose +^^^^^^^ +Collect a JSON or CSV inventory of components from ABOUT files. + +Options +^^^^^^^ + +:: + + -filter TEXT + + Filter for the output inventory. + + $ about inventory --filter "license_expression=gpl-2.0" LOCATION OUTPUT + + The above command will only inventory the ABOUT files which have the "license_expression: gpl-2.0" + + -f, --format [json|csv] + + Set OUTPUT file format. [default: csv] + + $ about inventory -f json LOCATION OUTPUT + + --mapping + + See mapping.config for details + + --mapping-file + + Same behavior as `--mapping` but with custom mapping file + + $ about inventory --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT + + --mapping-output + + Same behavior as `--mapping-file` but with custom mapping file + In the custom mapping file, the left side is the custom key name where + the right side is the ABOUT field name. For instance, + Component: name + + The "Component" is a custom field name for the output + The "name" is one of the defaul ABOUT field name that user want to convert + + $ about inventory --mapping-output CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT + + --verbose + + This option tells the tool to show all errors found. + The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING' + + +Special Notes +------------- +Multiple licenses support format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The multiple licenses support format for CSV files are separated by line break + ++----------------+------+-----------------+----------------------+ +| about_resource | name | license_key | license_file | ++----------------+------+-----------------+----------------------+ +| test.tar.xz | test | | apache-2.0 | | apache-2.0.LICENSE | +| | | | mit | | mit.LICENSE | ++----------------+------+-----------------+----------------------+ + + +The multiple licenses support format for ABOUT files are by "grouping" with the keyword "licenses" + +:: + + about_resource: test.tar.xz + name: test + licenses: + - key: apache 2.0 + name: apache-2.0.LICENSE + - key: mit + name: mit.LICENSE + diff --git a/docs/source/aboutcode-toolkit/specification.rst b/docs/source/aboutcode-toolkit/specification.rst new file mode 100644 index 00000000..bfe418cb --- /dev/null +++ b/docs/source/aboutcode-toolkit/specification.rst @@ -0,0 +1,413 @@ +ABOUT File Specification v3.1.2 +=============================== + +Purpose +------- + +An ABOUT file provides a simple way to document the provenance (origin and +license) and other important or interesting information about a software +component. An ABOUT file is a small YAML formatted text file stored in the +codebase side-by-side with the software component file or archive that it +documents. No modification of the documented software is needed. + +The ABOUT format is plain text with field name/value pairs separated by a colon. +It is easy to read and create by hand and is designed first for humans, rather +than machines. The format is well-defined and structured just enough to make it +easy to process with software as well. It contains enough information to fulfill +key license requirements such as creating credits or attribution notices, +collecting redistributable source code, or providing information about new +versions of a software component. + + +Getting Started +~~~~~~~~~~~~~~~ + +A simple and valid ABOUT file named httpd.ABOUT may look like this:: + + about_resource: httpd-2.4.3.tar.gz + name: Apache HTTP Server + version: 2.4.3 + homepage_url: http://httpd.apache.org + download_url: http://archive.apache.org/dist/httpd/httpd-2.4.3.tar.gz + license_expression: apache-2.0 + licenses: + - key: apache-2.0 + - file: apache-2.0.LICENSE + notice_file: httpd.NOTICE + copyright: Copyright (c) 2012 The Apache Software Foundation. + +The meaning of this ABOUT file is: + +- The file "httpd-2.4.3.tar.gz" is stored in the same directory and side-by-side + with the ABOUT file "httpd.ABOUT" that documents it. + +- The name of this component is "Apache HTTP Server" with version "2.4.3". + +- The home URL for this component is http://httpd.apache.org + +- The file "httpd-2.4.3.tar.gz" was originally downloaded from + http://archive.apache.org/dist/httpd/httpd-2.4.3.tar.gz + +- In the same directory, "apache-2.0.LICENSE" and "httpd.NOTICE" are files that + contain respectively the license text and the notice text for this component. + +- This component is licensed under "apache-2.0" + + +Specification +------------- + +An ABOUT file is an ASCII YAML formatted text file. +Note that while Unicode characters are not supported in +an ABOUT file proper, external files can contain UTF-8 Unicode. + + +ABOUT file name +--------------- + +An ABOUT file name can use a limited set of characters and is suffixed with a +".ABOUT" extension using any combination of uppercase and lowercase characters. + +A file name can contain only these US-ASCII characters: + +- digits from 0 to 9 +- uppercase and lowercase letters from A to Z +- the following symbols: "_", "-", "+", ".", "(", ")", "~", "[", "]", "{", "}" + +- The case of a file name is not significant. On case-sensitive file systems + (such as on Linux), a tool must report an error if two ABOUT files stored in + the same directory have the same lowercase file name. This is to ensure that + ABOUT files can be used across file systems. The convention is to use a + lowercase file name and an uppercase ABOUT extension. + + +Lines of text +------------- + +An ABOUT file contains lines of US-ASCII text. Lines contain field names/values +pairs. The standard line ending is the LF character. The line ending characters +can be any LF, CR or CR/LF and tools must normalize line endings to LF when +processing an ABOUT file. Empty lines and lines containing only white spaces +that are not part of a field value continuation are ignored. Empty lines are +commonly used to improve the readability of an ABOUT file. + + +Field name +---------- + +A field name can contain only these US-ASCII characters: + +- digits from 0 to 9 +- uppercase and lowercase letters from A to Z +- the "_" underscore sign. + +- Field names are not case sensitive. For example, "HOMEPAGE_URL" and "HomePage_url" + represent the same field name. + +- A field name must start at the beginning of a new line. It can be followed by + one or more spaces that must be ignored. These spaces are commonly used to + improve the readability of an ABOUT file. + + +Field value +----------- + +The field value is separated from the field name by a ":" colon. The ":" colon +can be followed by one or more spaces that must be ignored. This also applies to +trailing white spaces: they must be ignored. + +The field value is composed of one or more lines of plain US-ASCII printable text. + +When a field value is a long string, additional continuation lines must start +with at least one space. In this case, the first space of an additional +continuation line is ignored and should be removed from the field value by tools. + +For instance:: + + description: This is a long description for a + software component that additional continuation line is used. + + + When a field value contains more than one line of text, a 'literal block' + (using |) is need. + +For instance:: + + description: | + This is a long description for a software component that spans + multiple lines with arbitrary line breaks. + + This text contains multiple lines. + + +Fields are mandatory or optional +-------------------------------- + +As defined in this specification, a field can be mandatory or optional. Tools +must report an error for missing mandatory fields. + + +Extension and ignored fields +---------------------------- + +An ignored field is a field with a name that is not defined in this +specification. Custom extension fields are also supported and must be processed +by tools as ignored fields unless a certain tool can process a certain extension +field. + + +Fields validation +----------------- + +When processing an ABOUT file, tools must report a warning or error if a field +is invalid. A field can be invalid for several reasons, such as invalid field +name syntax or invalid content. Tools should report additional validation error +details. The validation process should check that each field name is +syntactically correct and that fields contain correct values according to its +concise, common sense definition in this specification. For certain fields, +additional and specific validations are relevant such as checksum verification, +URL validation, path resolution and verification, and so forth. Tools should +report a warning for ignored fields. + + +Fields order and multiple occurrences +------------------------------------- + +The field order does not matter. Multiple occurrences of a field name is not +supported. + +The tool processing an ABOUT file or CSV/JSON input will issue an error when a +field name occurs more than once in the input file (as for any other ignored field). + + +Field referencing a file +------------------------ + +The actual value of some fields may be contained in another file. This is useful +for long texts or to reference a common text in multiple ABOUT files such as a +common license text. In this case the field name is suffixed with "_file" and +the field value must be a path pointing to the file that contains the actual +value of the field. This path must be a POSIX path relative to the path of the +ABOUT file. The file content must be UTF-8-encoded text. This is in contrast +with field values contained directly in an ABOUT file that must be US-ASCII- +encoded text and allows to support non-ASCII text content. + +For example, the full license text for a component is often stored in a separate +file named COPYING:: + + licenses: + - file: linux.COPYING + +In this example, the README file is stored in a doc directory, one directory +above the ABOUT file directory, using a relative POSIX path:: + + licenses: + - file: ../docs/ruby.README + +Field referencing a URL +----------------------- + +The value of a field may reference URLs such as a homepage or a download. In +this case the field name is suffixed with "_url" and the field value must be a +valid absolute URL starting with ftp://, http:// or https://. URLs are +informational and the content they may reference is ignored. For example, a +download URL is referenced this way:: + + download_url: http://www.kernel.org/pub/linux/kernel/v3.0/linux-3.4.20.tar.bz2 + + +Flag fields +----------- + +Flag fields have a "true" or "false" value. True, T, Yes or Y , x must be +interpreted as "true" in any case combination. False, F, No or N must be +interpreted as "false" in any case combination. + +Referencing the file or directory documented by an ABOUT file +------------------------------------------------------------- + +An ABOUT file documents one file or directory. The mandatory "about_resource" +field reference the documented file or directory. The value of the +"about_resource" field is the name or path of the referenced file or directory. + +A tool processing an ABOUT file must report an error if this field is missing. + +By convention, an ABOUT file is often stored in the same directory side-by-side +to the file or directory that it documents, but this is not mandatory. + +For example, a file named django.ABOUT contains the following field to document +the django-1.2.3.tar.gz archive stored in the same directory:: + + about_resource: django-1.2.3.tar.gz + +In this example, the ABOUT file documents a whole sub-directory:: + + about_resource: linux-kernel-2.6.23 + +In this example, the ABOUT file documents the current directory, using a "." +period to reference it:: + + about_resource: . + + +Other Mandatory fields +---------------------- + +When a tool processes an ABOUT file, it must issue an error if these mandatory +field are missing. + +- about_resource: The resource this file referencing to. +- name: Component name. + + +Optional Information fields +--------------------------- + +- version: Component or package version. A component or package usually has a version, such as a + revision number or hash from a version control system (for a snapshot checked + out from VCS such as Subversion or Git). If not available, the version should + be the date the component was provisioned, in an ISO date format such as + 'YYYY-MM-DD'. + +- spec_version: The version of the ABOUT file format specification used for this + file. This is provided as a hint to readers and tools in order to support + future versions of this specification. + +- description: Component description, as a short text. + +- download_url: A direct URL to download the original file or archive documented + by this ABOUT file. + +- homepage_url: URL to the homepage for this component. + +- changelog_file: Changelog file for the component. + +- notes: Notes and comments about the component. + + +Optional Owner and Author fields +-------------------------------- + +- owner: The name of the primary organization or person(s) that owns or provides + the component. + +- owner_url: URL to the homepage for the owner. + +- contact: Contact information (such as an email address or physical address) + for the component owner. + +- author: Name of the organization(s) or person(s) that authored the component. + +- author_file: Author file for the component. + + +Optional Licensing fields +------------------------- + +- copyright: Copyright statement for the component. + +- notice_file: Legal notice or credits for the component. + +- notice_url: URL to a legal notice for the component. + +- license_file: License file that applies to the component. For example, the + name of a license file such as LICENSE or COPYING file extracted from a + downloaded archive. + +- license_url: URL to the license text for the component. + +- license_expression: The license expression that apply to the component. You + can separate each identifier using " or " and " and " to document the + relationship between multiple license identifiers, such as a choice among + multiple licenses. + +- license_name: The license short name for the license. + +- license_key: The license key(s) for the component. + + +Optional Boolean flag fields +---------------------------- + +- redistribute: Set this flag to yes if the component license requires source + code redistribution. Defaults to no when absent. + +- attribute: Set this flag to yes if the component license requires publishing + an attribution or credit notice. Defaults to no when absent. + +- track_changes: Set this flag to yes if the component license requires tracking + changes made to a the component. Defaults to no when absent. + +- modified: Set this flag to yes if the component has been modified. Defaults to + no when absent. + +- internal_use_only: Set this flag to yes if the component is used internal only. + Defaults to no when absent. + +Optional Extension fields +------------------------- + +You can create extension fields by prefixing them with a short prefix to +distinguish these from the standard fields. You should provide documentation for +these extensions and create or extend existing tools to support these +extensions. Other tools must ignore these extensions. + + +Optional Extension fields to reference files stored in a version control system (VCS) +------------------------------------------------------------------------------------- + +These fields provide a simple way to reference files stored in a version control +system. There are many VCS tools such as CVS, Subversion, Git, ClearCase and GNU +Arch. Accurate addressing of a file or directory revision in each tool in a +uniform way may not be possible. Some tools may require access control via +user/password or certificate and this information should not be stored in an +ABOUT file. This extension defines the 'vcs' field extension prefix and a few +common fields to handle the diversity of ways that VCS tools reference files and +directories under version control: + +- vcs_tool: VCS tool such as git, svn, cvs, etc. + +- vcs_repository: Typically a URL or some other identifier used by a VCS tool to + point to a repository such as an SVN or Git repository URL. + +- vcs_path: Path used by a particular VCS tool to point to a file, directory or + module inside a repository. + +- vcs_tag: tag name or path used by a particular VCS tool. + +- vcs_branch: branch name or path used by a particular VCS tool. + +- vcs_revision: revision identifier such as a revision hash or version number. + + +Some examples for using the vcs_* extension fields include:: + + vcs_tool: svn + vcs_repository: http://svn.code.sf.net/p/inkscape/code/inkscape_project/ + vcs_path: trunk/inkscape_planet/ + vcs_revision: 22886 + +or:: + + vcs_tool: git + vcs_repository: git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git + vcs_path: tools/lib/traceevent + vcs_revision: b59958d90b3e75a3b66cd311661535f94f5be4d1 + + +Optional Extension fields for checksums +--------------------------------------- + +These fields support checksums (such as SHA1 and MD5)commonly provided with +downloaded archives to verify their integrity. A tool can optionally use these +to verify the integrity of a file documented by an ABOUT file. + +- checksum_md5: MD5 for the file documented by this ABOUT file in the + "about_resource" field. + +- checksum_sha1: SHA1 for the file documented by this ABOUT file in the + "about_resource" field. + +Some examples:: + + checksum_md5: f30b9c173b1f19cf42ffa44f78e4b96c diff --git a/docs/source/index.rst b/docs/source/index.rst index fdabf496..0a880e35 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,6 +9,7 @@ Guide scancode-toolkit/index scancode-workbench/index + aboutcode-toolkit/index license help doc_maintenance