Skip to content

Commit dc62acc

Browse files
NdpntNdpnt
authored
Update metadata documentation (#156)
2 parents 491dfed + 8f6595a commit dc62acc

File tree

4 files changed

+174
-76
lines changed

4 files changed

+174
-76
lines changed

‎content/collections/create.en.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ You are considering creating a new collection to track terms with Open Terms A
99

1010
## Define metadata
1111

12-
First of all, define the [metadata]({{< relref "collections/metadata" >}}) of the collection you would like to create.
12+
First of all, define the [metadata]({{< relref "collections/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories.
1313

1414
## Check existing collections
1515

@@ -80,6 +80,10 @@ Issues labels will be added by the engine as problems are encountered when track
8080

8181
- Update the README file with proper metadata: topic, maintainers, jurisdictions, languages…
8282

83+
#### Update metadata
84+
85+
- Update the metadata file `metadata.yml` with the collection metadata you defined earlier.
86+
8387
### Snapshots
8488

8589
Create the snapshots repository by using the [`demo-snapshots` repository](https://github.com/OpenTermsArchive/demo-snapshots) as template:

‎content/collections/metadata.en.md‎

Lines changed: 146 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -7,61 +7,149 @@ weight: 1
77

88
A collection is defined by the following metadata.
99

10-
## Description
11-
12-
A concise description of the collection topic.
13-
14-
### Examples
15-
16-
- Largest global social media
17-
- Most used social media in France
18-
- Dating apps
19-
- Platforms providing services to businesses
20-
21-
## Name
22-
23-
Three words maximum.
24-
25-
### Examples
26-
27-
- Platform Governance Archive
28-
- France Élections
29-
- Dating
30-
- P2B Compliance Assessment
31-
32-
## ID
33-
34-
An identifier derived from the collection name that can more easily be referenced in code. Use acronyms and replace spaces with dashes.
35-
36-
### Examples
37-
38-
- `pga`
39-
- `France-elections`
40-
- `dating`
41-
- `p2b-compliance`
42-
43-
## Language
44-
45-
The expected language of the terms in the collection.
46-
47-
### Examples
48-
49-
- `English`
50-
- `French`
51-
- `All EU languages`
52-
53-
## Jurisdiction
54-
55-
The expected jurisdiction in which the terms in the collection apply.
56-
57-
### Examples
58-
59-
- `EU`
60-
- `France`
61-
- `EEA`
62-
- `USA`
63-
- `global`
64-
65-
## Roles
66-
67-
The name, URL and logo of the entities that will take responsibility for each of the necessary governance [roles]({{< relref "collections/governance" >}}).
10+
## Required fields
11+
12+
| Field | Type | Description |
13+
|----------------|-----------------|---------------------------------------|
14+
| `name` | string | Display name of the collection (max 3 words) |
15+
| `id` | string | Unique identifier derived from name (acronyms, dash-separated) |
16+
| `tagline` | string | Concise description of collection topic |
17+
| `description` | string | Detailed context beyond tagline |
18+
| `languages` | Array of strings| [ISO 639 language codes](https://en.wikipedia.org/wiki/ISO_639) allowed in collection |
19+
| `jurisdictions`| Array of strings| [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) for covered jurisdictions |
20+
21+
Example:
22+
23+
```yaml
24+
name: Platform Governance Archive
25+
id: pga
26+
tagline: Largest global social media
27+
languages: [en, fr, de]
28+
jurisdictions: [EU]
29+
```
30+
31+
## Additional fields
32+
33+
Additional fields are optional but highly recommended to facilitate better discovery, comprehension, and utilization of the collection.
34+
35+
| Field | Type | Description |
36+
|----------------|-----------------|---------------------------------------|
37+
| `description` | string | Detailed context beyond tagline |
38+
| `dataset` | url | URL to released versions dataset |
39+
| `declarations` | url | URL to declarations repository |
40+
| `versions` | url | URL to versions repository |
41+
| `snapshots` | url | URL to snapshots repository |
42+
| `logo` | url | URL to the collection's logo. Optimized PNG transparent image (min width 240px) |
43+
| `donation` | url | URL to donation page |
44+
| `trackingPeriods`| tracking periods object | see [Tracking periods](#tracking-periods) section |
45+
| `governance` | governance object | see [Governance](#governance) section |
46+
47+
Example:
48+
49+
```yaml
50+
description: Comprehensive collection of terms of service from major global social media platforms.
51+
dataset: https://github.com/OpenTermsArchive/demo-versions/releases
52+
declarations: https://github.com/OpenTermsArchive/demo-declarations
53+
versions: https://github.com/OpenTermsArchive/demo-versions
54+
snapshots: https://github.com/OpenTermsArchive/demo-snapshots
55+
logo: https://opentermsarchive.org/images/collections/demo.png
56+
donation: https://opencollective.com/opentermsarchive
57+
```
58+
59+
### Tracking periods
60+
61+
Information about when and how terms are tracked:
62+
63+
| Field | Type | Description |
64+
|---------------|--------|--------------------------------------------|
65+
| `startDate` | date ([ISO 8601 format: YYYY-MM-DD](https://en.wikipedia.org/wiki/ISO_8601)) | The date when tracking started |
66+
| `endDate` | date ([ISO 8601 format: YYYY-MM-DD](https://en.wikipedia.org/wiki/ISO_8601)) | The date when tracking ended or will end. If not specified, tracking is ongoing. |
67+
| `schedule` | string | A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency |
68+
| `serverLocation`| string (city name, [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2)) | The geographic location of the tracking server |
69+
70+
Example:
71+
72+
```yaml
73+
trackingPeriods:
74+
startDate: 2023-01-01
75+
endDate: 2024-12-31
76+
schedule: "0 0 * * *"
77+
serverLocation: London, GB
78+
```
79+
80+
### Governance
81+
82+
Organizations responsible for collection roles:
83+
84+
| Field | Type | Description |
85+
|---------------|-----------------|----------------------------------------|
86+
| `hosts` | Array of organizations objects| Organizations hosting the collection |
87+
| `administrators`| Array of organizations objects| Organizations managing the collection |
88+
| `curators` | Array of organizations objects| Organizations curating the content |
89+
| `maintainers` | Array of organizations objects| Organizations maintaining the technical aspects |
90+
| `sponsors` | Array of organizations objects| Organizations providing support |
91+
92+
Each organization in the governance roles is defined by the following fields:
93+
94+
| Field | Type | Description |
95+
|---------------|--------|-------------------------------------------|
96+
| `name` | string | Name of the organization |
97+
| `url` | url | Website URL of the organization (optional) |
98+
| `logo` | url | URL to the organization's logo. Optimized PNG transparent image (min width 240px) (optional) |
99+
100+
Example:
101+
102+
```yaml
103+
governance:
104+
administrators:
105+
- name: Open Terms Archive
106+
url: https://opentermsarchive.org/
107+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
108+
curators: []
109+
maintainers: []
110+
hosts: []
111+
sponsors: []
112+
```
113+
114+
## Complete metadata example
115+
116+
```yaml
117+
id: demo
118+
name: Demo
119+
tagline: Services needed to operate the Open Terms Archive engine
120+
description: This demo collection serves as a reference implementation…
121+
dataset: https://github.com/OpenTermsArchive/demo-versions/releases
122+
declarations: https://github.com/OpenTermsArchive/demo-declarations
123+
versions: https://github.com/OpenTermsArchive/demo-versions
124+
snapshots: https://github.com/OpenTermsArchive/demo-snapshots
125+
logo: https://opentermsarchive.org/images/collections/demo.png
126+
donation: https://opencollective.com/opentermsarchive
127+
languages: [en]
128+
jurisdictions: [EU]
129+
trackingPeriods:
130+
startDate: 2023-01-01
131+
endDate: 2024-12-31
132+
schedule: "0 0 * * *"
133+
serverLocation: London, GB
134+
governance:
135+
hosts:
136+
- name: Ministry for Europe and Foreign Affairs
137+
url: https://www.diplomatie.gouv.fr/en/
138+
logo: https://opentermsarchive.org/images/contributors/meae.png
139+
administrators:
140+
- name: Open Terms Archive
141+
url: https://opentermsarchive.org/
142+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
143+
curators:
144+
- name: Open Terms Archive
145+
url: https://opentermsarchive.org/
146+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
147+
maintainers:
148+
- name: Open Terms Archive
149+
url: https://opentermsarchive.org/
150+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
151+
sponsors:
152+
- name: Ministry for Europe and Foreign Affairs
153+
url: https://www.diplomatie.gouv.fr/en/
154+
logo: https://opentermsarchive.org/images/contributors/meae.png
155+
```

‎themes/opentermsarchive/assets/css/components/textContent/textContent.css‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,8 @@
108108
& blockquote + h2,
109109
& .highlight + h2,
110110
& details + h2,
111-
& video + h2{
111+
& video + h2
112+
& table + h2 {
112113
margin-top: var(--m2XL);
113114
}
114115

@@ -118,7 +119,8 @@
118119
& blockquote + h3,
119120
& .highlight + h3,
120121
& details + h3,
121-
& video + h3 {
122+
& video + h3,
123+
& table + h2 {
122124
margin-top: var(--mXL);
123125
}
124126

@@ -195,14 +197,19 @@
195197
margin-bottom: var(--mM);
196198
}
197199

198-
& pre{
199-
padding:0.8rem;
200+
& pre {
201+
padding: 1.5rem;
200202
overflow-x: scroll;
201203
}
202204

205+
& :not(pre) > code {
206+
padding: 0.2em 0.4em;
207+
border-radius: 0.3em;
208+
}
209+
203210
& code {
204211
background-color: var(--colorBlack200);
205-
font-size: 0.95em;
212+
font-size: 0.9em;
206213
}
207214

208215
& button {

‎themes/opentermsarchive/assets/css/elements/table.css‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,29 @@
11
table {
22
border-collapse: collapse;
33
width: 100%;
4+
margin-bottom: var(--mM);
45

56
& thead {
67
& tr {
8+
79
& th {
8-
padding: var(--pXS) var(--pM);
9-
border-bottom: 1px solid var(--colorBlack300);
10-
border-right: 1px solid var(--colorBlack300);
10+
text-align: left;
11+
border: 1px solid var(--colorBlack300);
12+
padding: var(--pXS) var(--pS);
1113
background-color: var(--colorBlack200);
12-
13-
&:last-child {
14-
border-right: 1px solid var(--colorBlack200);
15-
}
16-
&:first-child {
17-
border-left: 1px solid var(--colorBlack200);
18-
}
1914
}
2015
}
2116
}
2217
& tbody {
2318
& tr {
2419
& td {
25-
padding: var(--pXS) var(--pM);
26-
border: 1px solid var(--colorBlack200);
20+
padding: var(--pXS) var(--pS);
21+
border: 1px solid var(--colorBlack300);
2722
}
2823
}
24+
25+
& tr:nth-child(2n) {
26+
background-color: rgb(246, 248, 250);
27+
}
2928
}
3029
}

0 commit comments

Comments
 (0)