readme.md 8.21 KB
Newer Older
Aral Balkan's avatar
Aral Balkan committed
1
# Better
Aral Balkan's avatar
Aral Balkan committed
2

Aral Balkan's avatar
Aral Balkan committed
3
Better protects you from unethical web sites. It makes your web experience safer, lighter, and faster.
Aral Balkan's avatar
Aral Balkan committed
4

Aral Balkan's avatar
Aral Balkan committed
5
Better enforces the [Ethical Design Manifesto](https://ind.ie/ethical-design). It helps the Web respect human rights, effort, and experience.
Aral Balkan's avatar
Aral Balkan committed
6

Aral Balkan's avatar
Aral Balkan committed
7
Better is curated by Ind.ie, a social enterprise that defends human rights. It’s free, open, and transparent.
Aral Balkan's avatar
Aral Balkan committed
8

Aral Balkan's avatar
Aral Balkan committed
9
## Content
Aral Balkan's avatar
Aral Balkan committed
10

Aral Balkan's avatar
Aral Balkan committed
11
This repository contains the Better content: Better’s database of information on trackers and other malware as well as the web sites that host them.
Aral Balkan's avatar
Aral Balkan committed
12

Aral Balkan's avatar
Aral Balkan committed
13
This content is in Blockdown format. Blockdown is an extension of Markdown with special vocabulary to describe web malware. Blockdown can also contain WebKit content blocking rules. The Blockdown pages in Better’s content repository both describe web malware and contain the rules to block them.
Aral Balkan's avatar
Aral Balkan committed
14

Aral Balkan's avatar
Aral Balkan committed
15
This content is processed by [Better Builder](https://source.ind.ie/better/builder) to generate the [Better web site](https://better.fyi) as well as the data for the [Better iOS App](https://source.ind.ie/better/app), including a WebKit `blockerList.json` file.
Aral Balkan's avatar
Aral Balkan committed
16

Aral Balkan's avatar
Aral Balkan committed
17
A seminal advantage of Better is that its database is human-readable, open, and extensible via pull requests. (The database is curated by Ind.ie using the Ethical Design Manifesto as the criteria for blocking rules.)
Aral Balkan's avatar
Aral Balkan committed
18

19
Contributing to the content is as easy as creating an account on [source.ind.ie](https://source.ind.ie) and editing a content page in your browser.
20

Aral Balkan's avatar
Aral Balkan committed
21
## I’m not a developer, I just want to experience a Better web.
22

Aral Balkan's avatar
Aral Balkan committed
23
Get Better from the App Store.
24

Aral Balkan's avatar
Aral Balkan committed
25 26 27 28 29 30
## How can I support Better?

Buying Better on the App Store is one way to support us. If you want to help with the ongoing costs of developing and maintaining Better, you can [donate to Ind.ie](https://ind.ie/fund/) or, even better, [become a patron](https://ind.ie/fund/) by setting up a recurring donation.

## I’m a developer, let me in!

31 32
The easiest way to get started is to follow the instructions in the readme for the [Better iOS app](https://source.ind.ie/better/app) repository.

33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
## Testing locally.

[Better Builder](https://source.ind.ie/better/builder) will automatically pick up your changes as you save and rebuild your local data.

To persist your changes locally, commit them in Git and push to origin:

```bash
git commit -am "My awesome content update"
git push origin master
```

Note that these changes will be destroyed if you run the Better Builder installer (or the Better iOS installer, which runs the Better Builder installer as part of its own installation process). To not lose any work, save your changes regularly by pushing to production, as explained below.

## Saving your changes by pushing to production

You can push to production with:

```bash
./save
```

Or, manually run what the save script does, which is:

```bash
git push live master
```

## Deployment

If you have commit rights to the content repository, just run the deployment script:

```bash
./deploy
```

This will create a tag (you will have to enter a tag mesage when prompted, describing the release) and push it to production. Please make sure that you have already committed your changes and pushed them to production either via `git push live master` or by running the `./save` script, which does the same thing.

70
# Guide to Blockdown
71

72 73
Better content is authored in Blockdown.

74 75
Blockdown is Markdown with an extended high-level vocabulary for describing web malware for the Better database.

76
## Sites
77 78 79

Site pages have the following sections:

80 81

### Ethical design violations
82 83 84 85 86 87 88

```markdown
## Ethical design violations
```

This is a list of ethical design violations that gets converted to a collection of badges on the rendered site pages.

89 90 91

#### Trackers

92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
The first badge is always the trackers badge. In Blockdown it is represented by a list item introduced by the word `Trackers`:

```markdown
  * Trackers (exposes you to NNN third-party sites)
```

We get the statistic for the number of third-party sites that a person browsing the site is exposed to by using [Mozilla Lightbeam](https://www.mozilla.org/en-US/lightbeam/).

Following the badge heading list item, there is a sublist of site URLs. For example, here’s an excerpt from the [cultofmac.com site page](https://better.fyi/sites/cultofmac.com):

```markdown
* Trackers (exposes you to 155 third-party sites)
  * w.soundcloud.com
  * goroost.com
  * taboola.com
  * google-syndication.com
  *
```

This gets automatically translated by [Better Builder](https://source.ind.ie/better/builder) to a badge similar to the one below:

113
![Screenshot of the trackers badge](images/readme/blockdown/trackers-badge-example.png)
114 115 116 117 118

Specifically, the builder counts the number of trackers for you and juxtapositions that with the number of third-party sites that you entered manually.

Tapping on the badge displays a popover with links to the actual trackers.

119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
![Screenshot of the trackers popover](images/readme/blockdown/trackers-popover-example.png)

Trackers is the only section that is required for a site entry. The other badges should be used as and when they apply to a site.


#### Aggressive

```markdown
* Aggressive: Attempts to block content blockers.
```

![Screenshot of the Aggressive Badge](images/readme/blockdown/aggressive-badge-example.png)


#### Doorslam

```markdown
* Doorslam: Interrupts and blocks using modal dialogs.
```

![Screenshot of the Doorslam Badge](images/readme/blockdown/doorslam-badge-example.png)


#### Clickbait

```markdown
* Clickbait: Uses exploitative, addictive content syndication network(s).
```

![Screenshot of the Clickbait Badge](images/readme/blockdown/clickbait-badge-example.png)


#### Fingerprint

```markdown
* Fingerprint: Uses hidden Canvas fingerprinting.
```

![Screenshot of the Fingerprint Badge](images/readme/blockdown/fingerprint-badge-example.png)


#### Web Bugs

```markdown
* Web bugs: Uses invisible tracking pixels.
```

![Screenshot of the Web Bugs Badge](images/readme/blockdown/web-bugs-badge-example.png)

We might create new badges as and when we find new types of web malware and unethical practices to document and warn people about.
169 170 171 172 173 174 175

## After Better section

```markdown
## After Better
```

176
The After Better section provides statistics about the before (without the Better content blocker active) and after (with the Better content blocker active) performance of a site.
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217

The statistics are gathered using the Safari Web Inspector’s Timelines view.

Here is an example from the [cultofmac.com site page](https://better.fyi/sites/cultofmac.com):

```markdown
  * Weight: 11.5MB to 3.22MB
  * Speed: 10.38secs to 1.75secs
  * Resources: 458 to 63
  * Errors: 422 to 2
  * Warnings: 19 to 13
```

The statistics in this section are translated into a graph and table view for the app and the site by Better Builder.

![Screenshot of the After Better Section](images/readme/blockdown/after-better.png)

## Block Rules section

This is the section where we enter the actual WebKit content blocking rules. Each rule is written in a strict subset of MSON (Markdown JSON) and has a brief explanation detailing what the rule does and why.

The blocking rules in this section serve the following purposes, in line with the [Ethical Design Manifesto](https://ind.ie/ethical-design)

  * Remove any first-party trackers (respect human rights)
  * Improve the usability of the site by removing first-party impediments like doorslams (respect human effort)
  * Improve the experience of the site (respect human effort) – we should especially aim to create a better experience after trackers have been removed (like removing empty spaces left over, etc.)

Please note that this is not the place to put blocking rules for trackers. Each tracker encountered should be entered into the [Trackers](#trackers) section and you have its own page in the `/trackers` section of the content.

Here is an example of a site-specific blocking rule in MSON format:

```markdown
```mson
- trigger:
  - url-filter: cdn.cultofmac.com/wp-content/plugins/com2014-ads/static/js/frontend-functionality.js
- action:
  - type: block
``` 
```

The Blockdown parser in Better supports all of the [WebKit content blocking rules](https://webkit.org/blog/3476/content-blockers-first-look/). Instead of JSON, however, we enter blocking rules in MSON. All Blockdown rules are combined by Better Builder into a single `blockerList.json` file.