You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 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.
4
+
5
+
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.
6
+
7
+
Getting Started
8
+
A simple and valid ABOUT file named httpd.ABOUT may look like this:
copyright: Copyright (c) 2012 The Apache Software Foundation.
21
+
license_spdx: Apache-2.0
22
+
23
+
The meaning of this ABOUT file is:
24
+
25
+
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.
26
+
The name of this component is "Apache HTTP Server" with version "2.4.3".
27
+
The home URL for this component is http://httpd.apache.org
28
+
The file "httpd-2.4.3.tar.gz" was originally downloaded from http://archive.apache.org/dist/httpd/httpd-2.4.3.tar.gz
29
+
In the same directory, "httpd.LICENSE" and "httpd.NOTICE" are files that contain respectively the license text and the notice text for this component.
30
+
This component SPDX license identifier is "Apache-2.0"
31
+
Specification
32
+
An ABOUT file is an ASCII text file with lines of colon-separated "field name":"value" pairs. This format is loosely based on the Email header field format as specified in RFC5322/RFC822 at http://tools.ietf.org/html/rfc5322 . By reusing this specification, several available tools and libraries can parse and interpret ABOUT files. Note that while Unicode characters are not supported in an ABOUT file proper, external files can contain UTF-8 Unicode.
33
+
34
+
ABOUT file name
35
+
36
+
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.
37
+
38
+
A file name can contain only these US-ASCII characters:
39
+
40
+
digits from 0 to 9
41
+
uppercase and lowercase letters from A to Z
42
+
the "_" underscore, "-" dash and "." period signs.
43
+
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.
44
+
45
+
Lines of text
46
+
47
+
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.
48
+
49
+
Field name
50
+
51
+
A field name can contain only these US-ASCII characters:
52
+
53
+
digits from 0 to 9
54
+
uppercase and lowercase letters from A to Z
55
+
the "_" underscore sign.
56
+
Field names are not case sensitive. For example, "HOME_URL" and "Home_url" represent the same field name.
57
+
58
+
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.
59
+
60
+
Field value
61
+
62
+
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.
63
+
64
+
The field value is composed of one or more lines of plain US-ASCII printable text.
65
+
66
+
When a field value contains more than one line of text, 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.
67
+
68
+
In this example the value of the description field spans multiple lines:
69
+
70
+
description: This is a long description for a
71
+
software component that spans multiple lines with arbitrary line breaks.
72
+
73
+
Fields are mandatory or optional
74
+
75
+
As defined in this specification, a field can be mandatory or optional. Tools must report an error for missing mandatory fields.
76
+
77
+
Extension and ignored fields
78
+
79
+
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.
80
+
81
+
Fields validation
82
+
83
+
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.
84
+
85
+
Fields order and precedence
86
+
87
+
The field order does not matter with the following exception: multiple occurrences of a field name are possible and must be interpreted such that only the last occurrence is considered as the value for this field name. Previous occurrences of the same field name must be treated as ignored fields.
88
+
89
+
A tool processing an ABOUT file must issue a warning when a field name occurs more than once in an ABOUT file (as for any other ignored field).
90
+
91
+
Field referencing a file
92
+
93
+
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.
94
+
95
+
When an ABOUT file contains both a field name and a _file-suffixed field for the same field name, both fields must be treated as multiple occurrences of the same field name. This must be interpreted such that only the last occurrence is considered as the value for this field name.
96
+
97
+
For example, the full license text for a component is often stored in a separate file named COPYING:
98
+
99
+
license_text_file: linux.COPYING
100
+
101
+
In this example, the README file is stored in a doc directory, one directory above the ABOUT file directory, using a relative POSIX path:
102
+
103
+
license_text_file: ../docs/ruby.README
104
+
105
+
Field referencing a URL
106
+
107
+
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:
Flag fields have a "true" or "false" value. True, T, Yes or Y must be interpreted as "true" in any case combination. False, F, No or N must be interpreted as "false" in any case combination.
114
+
115
+
Referencing the file or directory documented by an ABOUT file
116
+
117
+
An ABOUT file documents one file or directory. The mandatory "about_resource" field points to the documented file or directory. The value of the "about_resource" field can be a name stored in the same directory as the ABOUT file or a POSIX path relative to the path of the ABOUT file. POSIX paths use a "/" forward slash sign as path separators.
118
+
119
+
A tool processing an ABOUT file must report an error if this field is missing.
120
+
121
+
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.
122
+
123
+
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:
124
+
125
+
about_resource: django-1.2.3.tar.gz
126
+
127
+
In this example, the ABOUT file documents a whole sub-directory:
128
+
129
+
about_resource: downloads/linux-kernel-2.6.23/
130
+
131
+
In this example, the ABOUT file documents the current directory, using a "." period to reference it:
132
+
133
+
about_resource: .
134
+
135
+
Since all paths are interpreted relative to the ABOUT file location, this would also reference the current directory:
136
+
137
+
about_resource: /
138
+
139
+
Other Mandatory fields
140
+
141
+
When a tool processes an ABOUT file, it must issue an error if these mandatory field are missing.
142
+
143
+
name: Component name.
144
+
version: Component version. A component 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'.
145
+
Optional Information fields
146
+
147
+
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.
148
+
description and description_file: Component description, as a short text or an external file.
149
+
download_url: A direct URL to download the original file or archive documented by this ABOUT file.
150
+
home_url: URL to the homepage for this component.
151
+
date: The date ('YYYY-MM-DD') when this ABOUT file was created or last validated (such as the date when the URLs were verified). ISO date format such as 'YYYY-MM-DD'.
152
+
readme and readme_file: Readme information for the component, as a short text or an external file.
153
+
changelog and changelog_file: Changelog text for the component, as a short text or an external file.
154
+
news and news_file: News text for the component, as a short text or an external file.
155
+
news_url: URL to a news feed for the component.
156
+
notes and notes_file: Notes and comments about the component, as a short text or an external file.
157
+
Optional Owner and Author fields
158
+
159
+
owner: The name of the primary organization or person(s) that owns or provides the component.
160
+
contact: Contact information (such as an email address or physical address) for the component owner.
161
+
author and author_file: Name of the organization(s) or person(s) that authored the component, as a short text or an external file.
162
+
Optional Licensing fields
163
+
164
+
copyright and copyright_file: Copyright statement for the component, as a short text or an external file.
165
+
notice and notice_file: Legal notice or credits for the component, as a short text or an external file.
166
+
notice_url: URL to a legal notice for the component.
167
+
license_text and license_text_file: License text that applies to the component, as a short text or an external file. For example, the name of a license file such as LICENSE or COPYING file extracted from a downloaded archive.
168
+
license_url: URL to the license text for the component.
169
+
license_spdx: The SPDX license short form identifiers for the license of this component. See http://spdx.org/licenses/ for details. You can separate each identifier using " or " and " and " as defined in the SPDX specification 1.1 to document the relationship between multiple license identifiers, such as a choice among multiple licenses. The case of the SPDX ID is not significant, such that APACHE-1.1 and apache-1.1 are the same field value. Tools should normalize the case of the ID to be the official case sensitive SPDX ID.
170
+
Optional Licensing flag fields
171
+
172
+
redistribute: Set this flag to yes if the component license requires source code redistribution. Defaults to no when absent.
173
+
attribute: Set this flag to yes if the component license requires publishing an attribution or credit notice. Defaults to no when absent.
174
+
track_changes: Set this flag to yes if the component license requires tracking changes made to a the component. Defaults to no when absent.
175
+
Optional Extension fields
176
+
177
+
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.
178
+
179
+
Optional Extension fields to reference files stored in a version control system (VCS)
180
+
181
+
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:
182
+
183
+
vcs_tool: VCS tool such as git, svn, cvs, etc.
184
+
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.
185
+
vcs_path: Path used by a particular VCS tool to point to a file, directory or module inside a repository.
186
+
vcs_tag: tag name or path used by a particular VCS tool.
187
+
vcs_branch: branch name or path used by a particular VCS tool.
188
+
vcs_revision: revision identifier such as a revision hash or version number.
189
+
Some examples for using the vcs_* extension fields include:
Optional Extension fields for checksums and digital signatures
204
+
205
+
These fields support checksums (such as SHA1 and MD5) and signatures (such as GPG) 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. This extension defines the "checksum_" and "signature_" field extension prefixes with suffix identifiers of the type of signature or checksum such as in "checksum_sha1".
206
+
207
+
checksum_sha1, checksum_md5, checksum_sha256, checksum_sha512: Checksum for the file documented by this ABOUT file in the "about_resource" field. The suffix defines the checksum algorithm such as "_md5", "_sha1", "_sha256". The checksum algorithms and formats are as defined in the GNU Coreutils tools md5sum, sha1sum and sha256sum commands ( http://www.gnu.org/software/coreutils/ ) that follow the specifications defined in the FIPS-180-2 standard ( http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf ). Files can be referenced with the "_file" suffix such as with "checksum_sha1_file" to reference checksums files commonly provided such as here: http://mirrors.ibiblio.org/maven2/org/jdom/jdom/1.1.2/jdom-1.1.2-javadoc.jar.md5
208
+
signature_gpg, signature_gpg_file, signature_pgp, signature_pgp_file: Signature or external signature file for the file documented by this ABOUT file in the "about_resource" field. Signature files for GPG and PGP are commonly provided to verify code archives integrity and provenance such as here: http://www.kernel.org/pub/linux/kernel/v3.0/linux-3.1.7.tar.sign or here: http://archive.apache.org/dist/maven/plugins/maven-acr-plugin-1.0-source-release.zip.asc or here:
0 commit comments