README.md
1# Compliance
2
3<!-- Much of this content appears too in doc.go
4When changing this file consider whether the change also applies to doc.go -->
5
6Package compliance provides an approved means for reading, consuming, and
7analyzing license metadata graphs.
8
9Assuming the license metadata and dependencies are fully and accurately
10recorded in the build system, any discrepancy between the official policy for
11open source license compliance and this code is **a bug in this code.**
12
13## Naming
14
15All of the code that directly reflects a policy decision belongs in a file with
16a name begninning `policy_`. Changes to these files need to be authored or
17reviewed by someone in OSPO or whichever successor group governs policy.
18
19The files with names not beginning `policy_` describe data types, and general,
20reusable algorithms.
21
22The source code for binary tools and utilities appears under the `cmd/`
23subdirectory. Other subdirectories contain reusable components that are not
24`compliance` per se.
25
26## Data Types
27
28A few principal types to understand are LicenseGraph, LicenseCondition, and
29ResolutionSet.
30
31### LicenseGraph
32
33A LicenseGraph is an immutable graph of the targets and dependencies reachable
34from a specific set of root targets. In general, the root targets will be the
35artifacts in a release or distribution. While conceptually immutable, parts of
36the graph may be loaded or evaluated lazily.
37
38Conceptually, the graph itself will always be a directed acyclic graph. One
39representation is a set of directed edges. Another is a set of nodes with
40directed edges to their dependencies.
41
42The edges have annotations, which can distinguish between build tools, runtime
43dependencies, and dependencies like 'contains' that make a derivative work.
44
45### LicenseCondition
46
47A LicenseCondition is an immutable tuple pairing a condition name with an
48originating target. e.g. Per current policy, a static library licensed under an
49MIT license would pair a "notice" condition with the static library target, and
50a dynamic license licensed under GPL would pair a "restricted" condition with
51the dynamic library target.
52
53### ResolutionSet
54
55A ResolutionSet is an immutable set of `AttachesTo`, `ActsOn`, `Resolves`
56tuples describing how license conditions apply to targets.
57
58`AttachesTo` is the trigger for acting. Distribution of the target invokes
59the policy.
60
61`ActsOn` is the target to share, give notice for, hide etc.
62
63`Resolves` is the set of conditions that the action resolves.
64
65For most condition types, `ActsOn` will be the target where the condition
66originated. For example, a notice condition policy means attribution or notice
67must be given for the target where the condition originates. Likewise, a
68proprietary condition policy means the privacy of the target where the
69condition originates must be respected. i.e. The thing acted on is the origin.
70
71Restricted conditions are different. The infectious nature of restricted often
72means sharing code that is not the target where the restricted condition
73originates. Linking an MIT library to a GPL library implies a policy to share
74the MIT library despite the MIT license having no source sharing requirement.
75
76In this case, one or more resolution tuples will have the MIT license module in
77`ActsOn` and the restricted condition originating at the GPL library module in
78`Resolves`. These tuples will `AttachTo` every target that depends on the GPL
79library because shipping any of those targets trigger the policy to share the
80code.
81
82## Processes
83
84### ReadLicenseGraph
85
86The principal means to ingest license metadata. Given the distribution targets,
87ReadLicenseGraph populates the LicenseGraph for those root targets.
88
89### NoticeIndex.IndexLicenseTexts
90
91IndexLicenseTexts reads, deduplicates and caches license texts for notice
92files. Also reads and caches project metadata for deriving library names.
93
94The algorithm for deriving library names has not been dictated by OSPO policy,
95but reflects a pragmatic attempt to comply with Android policy regarding
96unreleased product names, proprietary partner names etc.
97
98### projectmetadata.Index.MetadataForProjects
99
100MetadataForProjects reads, deduplicates and caches project METADATA files used
101for notice library names, and various properties appearing in SBOMs.
102