Skip to content

Commit 4a5b2b7

Browse files
NdpntNdpnt
authored
Add local contribution guide (#69)
2 parents 89e2573 + 875fae9 commit 4a5b2b7

File tree

4 files changed

+144
-68
lines changed

4 files changed

+144
-68
lines changed

‎content/terms/how-to/track-new-terms.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,30 @@ aliases: /contributing-terms/
66

77
# How to track new terms
88

9-
Tracking terms is done by _declaring_ them and the service they are associated with. Such a declaration is achieved by editing JSON files in the [`declarations`](https://github.com/OpenTermsArchive/contrib-declarations/tree/main/declarations) folder.
9+
This is a step by step guide to help you add declarations to the [contrib-declaration](https://github.com/OpenTermsArchive/contrib-declarations) repository. This repository is dedicated for volunteer contribution of declarations to Open Terms Archive.
1010

11-
Before adding new terms, open the [`declarations`](https://github.com/OpenTermsArchive/contrib-declarations/tree/main/declarations) folder and check if the service you want to track terms for is already declared. If a JSON file with the name of the service is already present, you can jump straight to the [Terms reference]({{< relref "terms/reference" >}}). Otherwise, keep reading!
11+
Having understood briefly how a declaration is structured in JSON format, we need to look at concrete steps on how you can add these JSON files to the repository.
1212

13-
## Declaring a new service
13+
## Prerequisites
1414

15-
Before declaring a service, you will need to choose the service name and service ID. The service ID will be the name of the JSON file in which the service will be declared. It is a normalised version of the service name.
15+
In order to add declarations:
16+
17+
1. You need to have [Node.js](https://nodejs.org/en/) installed on your machine. If you don't have it, you can download it from the official website [here](https://nodejs.org/en/download/).
18+
2. You need to have git installed on your machine. If you don't have it, you can download it from the official website [here](https://git-scm.com/downloads).
19+
20+
## Adding a declaration
21+
22+
To add a declaration, you need to follow these steps:
23+
24+
1. Clone the [contrib-declaration](https://github.com/OpenTermsArchive/contrib-declarations) repository to your local machine.
25+
2. Create a branch that describes your contribution e.g. `add-Open-Terms-Archive-ToS` or `add-firefox-privacy-policy`
26+
3. Run `npm install`. This is to install all the dependencies including the Open Terms Archive engine which will allow you to test and validate your declaration to make sure it is ok.
27+
4. Create a JSON file with the name of the service you are adding the declaration for. This JSON file should be in the `declarations` folder of the repository. To learn more about selecting the right service name, please read the [Service name](#service-name) section below.
28+
5. Visit the declaration URL and use [browser developer tools](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/What_are_browser_developer_tools) to inspect the page and find the right selectors for the significant section containing the terms you want to declare.
29+
6. After you've properly added your selectors and structured your JSON file, you need to test and validate your JSON file to make sure it is ok. To do this, you need to run `npx ota validate --services [service name]` from the root of the repository. This will run a validation on the declaration, highlighting any changes required.
30+
7. If all tests are good, make a pull request to the main repository.
31+
32+
> If you have a hard time finding the service name, check out the [practical guidelines to find the service name]({{< relref "/terms/guidelines/declaring" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂
1633
1734
## Service name
1835

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

Lines changed: 117 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,170 @@
11
.aside {
22
flex-shrink: 0;
3-
margin-right:var(--mXL);
3+
margin-right: var(--mXL);
44
@mixin grid 3, 2;
5-
border:1px solid var(--colorBlack200);
6-
border-radius:4px;
5+
border: 1px solid var(--colorBlack200);
6+
border-radius: 4px;
77
}
88

99
@media (--tabletSmall) {
1010
.aside {
1111
max-width: 100%;
12-
margin-bottom:var(--m2XL);
12+
margin-bottom: var(--m2XL);
1313
}
1414
}
1515

16-
.aside_nav{
17-
ul{
18-
color:var(--colorBlack600);
19-
display:flex;
20-
flex-direction:column;
16+
.aside_nav {
17+
> ul > li > details > ul > li:last-child,
18+
> ul > li > details > ul > li:not(:last-child) > ul {
19+
margin-bottom: var(--mS);
20+
}
21+
22+
ul {
23+
color: var(--colorBlack600);
24+
display: flex;
25+
flex-direction: column;
2126

22-
li{
23-
border-bottom:1px solid var(--colorBlack200);
27+
li {
28+
position: relative;
29+
border-bottom: 1px solid var(--colorBlack200);
30+
31+
&:last-child {
32+
border: none;
33+
}
2434

25-
a{
35+
a {
2636
padding: var(--mXS) var(--mS);
27-
display:inline-block;
28-
width:100%;
37+
display: inline-block;
38+
width: 100%;
39+
}
40+
41+
.aside_item-current {
42+
color: var(--colorBlack800);
43+
44+
&::before {
45+
content: '';
46+
position: absolute;
47+
left: 0;
48+
width: 4px;
49+
background-color: var(--colorPrimary);
50+
border-radius: 0 10px 10px 0;
51+
z-index: 1;
52+
top: var(--m2XS);
53+
bottom: var(--m2XS);
54+
}
2955

30-
&:hover{
31-
background-color:var(--colorBlack200);
56+
&::after {
57+
content: '';
58+
position: absolute;
59+
background-color: var(--colorBlack200);
60+
border-radius: 4px;
61+
z-index: -1;
62+
left: var(--mXS);
63+
right: var(--m2XS);
64+
top: var(--m2XS);
65+
bottom: var(--m2XS);
3266
}
3367
}
3468

35-
&:last-child{
36-
border:none;
69+
&.aside_item-current-section {
70+
&::before {
71+
content: '';
72+
position: absolute;
73+
left: 0;
74+
top: 0;
75+
bottom: 0;
76+
width: 1px;
77+
background-color: var(--colorPrimary);
78+
border-radius: 0;
79+
}
80+
81+
& .aside_item-current {
82+
&::before {
83+
top: 2px;
84+
bottom: 2px;
85+
}
86+
87+
&::after {
88+
top: 0;
89+
bottom: 0;
90+
right: var(--mXS);
91+
}
92+
}
3793
}
3894

39-
details{
95+
details {
4096
position: relative;
4197

42-
summary{
98+
summary {
4399
padding: var(--mXS) var(--mS);
44100
list-style: none;
45101
cursor: pointer;
46102

47-
&:hover{
48-
background-color:var(--colorBlack200);
49-
}
50-
51103
&::marker,
52-
&::-webkit-details-marker{
104+
&::-webkit-details-marker {
53105
display: none;
54106
}
55-
56-
& svg{
107+
108+
& svg {
57109
position: absolute;
58110
right: 10px;
59-
top:14px;
60-
font-size:0.8em;
61-
color:var(--colorBlack400);
111+
top: 14px;
112+
font-size: 0.8em;
113+
color: var(--colorBlack400);
62114
transition: transform 0.2s ease;
63115
}
64-
}
65116

66-
&[open]{
67-
summary > svg{
68-
transform: rotate(180deg);
117+
&:hover::after {
118+
content: '';
119+
position: absolute;
120+
inset: 0;
121+
background-color: var(--colorBlack100);
122+
z-index: -1;
69123
}
70124
}
125+
126+
&[open] summary > svg {
127+
transform: rotate(180deg);
128+
}
71129
}
72130

73-
span{
74-
display:inline-block;
131+
span {
132+
display: inline-block;
75133
}
76134
}
77135

78-
ul{
79-
padding-left:var(--mS);
80-
padding-top:var(--m2XS);
81-
padding-bottom:var(--m2XS);
136+
ul {
137+
li {
138+
border: none;
82139

83-
li{
84-
border:none;
85-
padding-top:var(--m3XS);
86-
padding-bottom:var(--m3XS);
140+
a {
141+
padding: var(--p3XS) var(--mL);
142+
border-radius: 4px;
143+
}
87144

88-
a{
89-
padding: 0;
145+
> span,
146+
a {
147+
padding-left: var(--mS);
148+
}
90149

91-
&:hover{
92-
background-color: transparent;
93-
}
150+
> a {
151+
padding-top: var(--p3XS);
152+
padding-bottom: var(--p3XS);
94153
}
95154

96-
ul{
97-
padding-top:0;
98-
padding-bottom:0;
155+
ul {
156+
padding-top: 0;
157+
158+
li {
159+
padding: 0;
99160

100-
li{
101-
padding:0;
161+
a {
162+
padding: var(--p3XS) var(--mL);
163+
border-radius: 4px;
164+
}
102165
}
103166
}
104167
}
105168
}
106169
}
107170
}
108-
109-
.aside_item-current{
110-
border-left:2px solid var(--colorPrimary);
111-
}
112-

‎themes/opentermsarchive/assets/css/custom-properties.css‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
--colorBlack400: #999;
2727
--colorBlack300: #d6d6d6;
2828
--colorBlack200: #f5f5f5;
29+
--colorBlack100: #fafafa;
2930
--colorWhite: #fefffd;
3031

3132
/* Padding & margin */

‎themes/opentermsarchive/layouts/partials/aside.html‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44

55
<nav class="aside_nav">
66
<ul>
7-
<li class="{{ if eq $currentPageRelPermalink .Site.Home.RelPermalink }}aside_item-current{{ end }}"><a href="{{ .Site.Home.RelPermalink }}">{{ .Site.Home.LinkTitle }}</a></li>
7+
<li ><b><a class="{{ if eq $currentPageRelPermalink .Site.Home.RelPermalink }}aside_item-current{{ end }}" href="{{ .Site.Home.RelPermalink }}">{{ .Site.Home.LinkTitle }}</a></b></li>
88
{{ range .Site.Sections.ByWeight }}
9-
<li class="{{ if eq $currentPageSection .Section }}aside_item-current{{ end }}">
9+
<li class="{{ if eq $currentPageSection .Section }}aside_item-current-section{{ end }}">
1010
<details {{ if eq $currentPageSection .Section }}open{{ end }}>
1111
<summary><b>{{ .LinkTitle | markdownify }}</b> <i class="icon" data-lucide="chevron-down"></i></summary>
1212
<ul>
@@ -15,14 +15,14 @@
1515
{{ range $allPages }}
1616
<li>
1717
{{ if .Content }}
18-
<a href="{{ .RelPermalink }}">{{ .LinkTitle | markdownify }}</a>
18+
<a class="{{ if eq $currentPageRelPermalink .RelPermalink }}aside_item-current{{ end }}" href="{{ .RelPermalink }}">{{ .LinkTitle | markdownify }}</a>
1919
{{ else }}
20-
<span>{{ .LinkTitle | markdownify }}</span>
20+
<span class="{{ if eq $currentPageRelPermalink .RelPermalink }}aside_item-current{{ end }}">{{ .LinkTitle | markdownify }}</span>
2121
{{ end }}
2222
{{ if .IsSection }}
2323
<ul>
2424
{{ range .RegularPages.ByWeight }}
25-
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle | markdownify }}</a></li>
25+
<li><a class="{{ if eq $currentPageRelPermalink .RelPermalink }}aside_item-current{{ end }}" href="{{ .RelPermalink }}">{{ .LinkTitle | markdownify }}</a></li>
2626
{{ end }}
2727
</ul>
2828
{{ end }}

0 commit comments

Comments
 (0)