From fe0434bf95238c1a746527cbe25b62f5869b5068 Mon Sep 17 00:00:00 2001 From: Alexis Hancock Date: Thu, 23 Jul 2020 14:35:29 -0700 Subject: [PATCH 1/3] Update Documentation - Create distinctions between users, contributors, and website owners - Provide guide links for all 3 - Comply more with Google Markdown style - Update Contributor guide and consolidate information --- CONTRIBUTING.md | 222 +++++++++++++++++++++++++++--------------------- README.md | 71 +++------------- 2 files changed, 137 insertions(+), 156 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2beb240cd4b8..7a9b6730a7c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,42 +1,43 @@ # Table of Contents -* [Welcome!](#welcome) - * [HTTPS Everywhere Source Code Layout](#https-everywhere-source-code-layout) - * [Submitting Changes](#submitting-changes) - * [I Want To Fix My Site](#i-want-to-fix-my-site) -* [Contributing Rulesets](#contributing-rulesets) - * [General Info](#general-info) - * [New Rulesets](#new-rulesets) - * [Minimum Requirements for a Ruleset PR](#minimum-requirements-for-a-ruleset-pr) - * [Testing](#testing) - * [Ruleset Style Guide](#ruleset-style-guide) - * [Motivation](#motivation) - * [Indentation & Misc Stylistic Conventions](#indentation--misc-stylistic-conventions) - * [Wildcards in Targets](#wildcards-in-targets) - * [Left-Wildcards](#left-wildcards) - * [Edge-Case: Right-Wildcards](#edge-case-right-wildcards) - * [Complicated Regex in Rules](#complicated-regex-in-rules) - * [Enumerating Subdomains](#enumerating-subdomains) - * [Target Ordering](#target-ordering) - * [Rule Ordering](#rule-ordering) - * [Non-working hosts](#non-working-hosts) - * [Ruleset Names](#ruleset-names) - * [Filenames](#filenames) - * [Cross-referencing Rulesets](#cross-referencing-rulesets) - * [Regex Conventions](#regex-conventions) - * [Snapping Redirects](#snapping-redirects) - * [Example: Ruleset before style guidelines are applied](#example-ruleset-before-style-guidelines-are-applied) - * [Example: Ruleset after style guidelines are applied, with test URLs](#example-ruleset-after-style-guidelines-are-applied-with-test-urls) - * [Removal of Rules](#removal-of-rules) - * [Regular Rules](#regular-rules) - * [HSTS Preloaded Rules](#hsts-preloaded-rules) -* [Contributing Code](#contributing-code) -* [Contributing Documentation](#contributing-documentation) -* [Contributing Translations](#contributing-translations) - -* * * - -# Welcome! +- [Table of Contents](#table-of-contents) +- [Welcome](#welcome) + - [HTTPS Everywhere Source Code Layout](#https-everywhere-source-code-layout) + - [Install Dependencies and Test Build](#install-dependencies-and-test-build) + - [Precommit Testing](#precommit-testing) + - [Submitting Changes](#submitting-changes) + - [Contributing Rulesets](#contributing-rulesets) + - [General Info](#general-info) + - [New Rulesets](#new-rulesets) + - [Minimum Requirements for a Ruleset PR](#minimum-requirements-for-a-ruleset-pr) + - [Testing](#testing) + - [Ruleset Style Guide](#ruleset-style-guide) + - [Motivation](#motivation) + - [Indentation & Misc Stylistic Conventions](#indentation--misc-stylistic-conventions) + - [Wildcards in Targets](#wildcards-in-targets) + - [Left-Wildcards](#left-wildcards) + - [Edge-Case: Right-Wildcards](#edge-case-right-wildcards) + - [Complicated Regex in Rules](#complicated-regex-in-rules) + - [Enumerating Subdomains](#enumerating-subdomains) + - [Target Ordering](#target-ordering) + - [Rule Ordering](#rule-ordering) + - [Non-working hosts](#non-working-hosts) + - [Ruleset Names](#ruleset-names) + - [Filenames](#filenames) + - [Cross-referencing Rulesets](#cross-referencing-rulesets) + - [Regex Conventions](#regex-conventions) + - [Snapping Redirects](#snapping-redirects) + - [Example: Ruleset before style guidelines are applied](#example-ruleset-before-style-guidelines-are-applied) + - [Example: Ruleset after style guidelines are applied, with test URLs](#example-ruleset-after-style-guidelines-are-applied-with-test-urls) + - [Removal of Rules](#removal-of-rules) + - [Regular Rules](#regular-rules) + - [HSTS Preloaded Rules](#hsts-preloaded-rules) + - [Contributing Code](#contributing-code) + - [Contributing Documentation](#contributing-documentation) + - [Pull Requests from Deleted Accounts](#pull-requests-from-deleted-accounts) + - [Contributing Translations](#contributing-translations) + +# Welcome Welcome, and thank you for your interest in contributing to HTTPS Everywhere! HTTPS Everywhere depends on the open source community for its continued success, so any contribution is appreciated. @@ -44,7 +45,7 @@ One of the things that makes it easy to contribute to HTTPS Everywhere is that y If you want to have the greatest impact, however, you can help be a ruleset maintainer. Ruleset maintainers are trusted volunteers who examine rulesets contributed by others and work with them to ensure that these rulesets work properly and are styled correctly before they're merged in. While we currently have a couple of extremely dedicated and extremely proficient ruleset maintainers, the backlog of sites to add to HTTPS Everywhere just keeps growing, and they need help! If you would like to volunteer to become one, the best thing to do is to build trust in your work by monitoring the repository, contributing pull requests, and commenting on issues that interest you. Then you can contact us at https-everywhere-rules-owner [at] eff <dot> org expressing your interest in helping out. -If you get stuck we have two publicly-archived mailing lists: the https-everywhere list (https://lists.eff.org/mailman/listinfo/https-everywhere) is for discussing the project as a whole, and the https-everywhere-rulesets list (https://lists.eff.org/mailman/listinfo/https-everywhere-rules) is for discussing the `rulesets` and their contents, including patches and git pull requests. +If you get stuck we have two publicly-archived mailing lists: the [https-everywhere list](https://lists.eff.org/mailman/listinfo/https-everywhere) is for discussing the project as a whole, and the [https-everywhere-rulesets list](https://lists.eff.org/mailman/listinfo/https-everywhere-rules) is for discussing the `rulesets` and their contents, including patches and git pull requests. You can also find more information on about HTTPS Everywhere on our [FAQ](https://www.eff.org/https-everywhere/faq) page. @@ -52,7 +53,6 @@ Also, please remember that this project is governed by [EFF's Public Projects Co Thanks again, and we look forward to your contributions! - ## HTTPS Everywhere Source Code Layout There are several main areas of development on HTTPS Everywhere: the rulesets, the core codebase, utilities, and tests. @@ -65,38 +65,75 @@ The utilities ([`utils`](utils) top-level path) include scripts that build the e Tests are performed in headless browsers and located in the [`test`](test) top-level path. These are written in Python, and some of the wrappers for these tests are in shell scripts. -## Submitting Changes +Source Tree: -To submit changes, open a pull request from our [GitHub repository](https://github.com/efforg/https-everywhere). + chromium/ WebExtension source code (for Firefox & Chromium/chrome) + chromium/external External dependencies + chromium/test Unit tests -HTTPS Everywhere is maintained by a limited set of staff and volunteers. Please be mindful that we may take a while before we're able to review your contributions. + rules/ Symbolic link to src/chrome/content/rules -## I Want To Fix My Site + src/chrome/content/rules Ruleset files live here -**"I want to get an SSL certificate"** + test/ Travis unit test source code live here -To get an SSL certificate, as an option, you can go to [Let's Encrypt](https://letsencrypt.org/) and get a free certificate. + utils/ Various utilities (includes some Travis test source) -**"I have an SSL certificate, but it's not configured properly"** +## Install Dependencies and Test Build -Scan your site at the [Mozilla Observatory](https://observatory.mozilla.org/) and get results on what is wrong/insecure about your site, as well as tips and directions on how to fix those issues. +Get the packages you need and install a git hook to run tests before push: -**"How do I get on the HSTS Preload list?"** + bash install-dev-dependencies.sh -In order to do this, you must have an SSL certificate correctly installed and your site redirecting to HTTPS. As well as meet a few extra requirements for the [`HTTP Strict-Transport-Security`](https://developer.mozilla.org/docs/Web/HTTP/Headers/Strict-Transport-Security) header. To view "how close" your site is for HSTS preloading, scan your site [here](https://hstspreload.org/). +Run the ruleset validations and browser tests: -* * * + bash test.sh + +Run the latest code and rulesets in a standalone Firefox profile: + + bash test/firefox.sh --justrun + +Run the latest code and rulesets in a standalone profile for a specific version of Firefox: + + FIREFOX=/path/to/firefox bash test/firefox.sh --justrun + +Run the latest code and rulesets in a standalone Chromium profile: + + bash test/chromium.sh --justrun + +Run the latest code and rulesets in a standalone Tor Browser profile: + + bash test/tor-browser.sh path_to_tor_browser.tar.xz + +Build the Firefox (.xpi) & Chromium (.crx) extensions: + + bash make.sh + +Both of the build commands store their output under pkg/. + +## Precommit Testing -# Contributing Rulesets +One can run the available test suites automatically by enabling the precommit +hook provided with: -## General Info + ln -s ../../hooks/precommit .git/hooks/pre-commit + +## Submitting Changes + +To submit changes, open a pull request from our [GitHub repository](https://github.com/efforg/https-everywhere). + +HTTPS Everywhere is maintained by a limited set of staff and volunteers. Please be mindful that we may take a while before we're able to review your contributions. + +## Contributing Rulesets + +### General Info Thanks for your interest in contributing to the HTTPS Everywhere `rulesets`! There's just a few things you should know before jumping in. First some terminology, which will help you understand how exactly `rulesets` are structured and what each one contains: -- `ruleset`: a scope in which `rules`, `targets`, and `tests` are contained. `rulesets` are usually named after the entity which controls the group of `targets` contained in it. There is one `ruleset` per XML file within the `src/chrome/content/rules` directory. -- `target`: a Fully Qualified Domain Name which may include a wildcard specified by `*.` on the left side, which `rules` are applied to. There may be many `targets` within any given `ruleset`. -- `rule`: a specific regular expression rewrite that is applied for all matching `targets` within the same `ruleset`. There may be many `rules` within any given `ruleset`. -- `test`: a URL for which a request is made to ensure that the rewrite is working properly. There may be many `tests` within any given `ruleset`. +* `ruleset`: a scope in which `rules`, `targets`, and `tests` are contained. `rulesets` are usually named after the entity which controls the group of `targets` contained in it. There is one `ruleset` per XML file within the `src/chrome/content/rules` directory. +* `target`: a Fully Qualified Domain Name which may include a wildcard specified by `*.` on the left side, which `rules` are applied to. There may be many `targets` within any given `ruleset`. +* `rule`: a specific regular expression rewrite that is applied for all matching `targets` within the same `ruleset`. There may be many `rules` within any given `ruleset`. +* `test`: a URL for which a request is made to ensure that the rewrite is working properly. There may be many `tests` within any given `ruleset`. ```xml - + - + - + ``` @@ -154,7 +154,7 @@ HTTPS Everywhere includes tens of thousands of `rulesets`. Any one of these sit Some `rulesets` have the attribute `platform="mixedcontent"`. These `rulesets` cause problems in browsers that enable active mixed-content (loading insecure resources in a secure page) blocking. When browsers started enforcing active mixed-content blocking, some HTTPS sites started to break. That's why we introduced this tag - it disables those `rulesets` for browsers blocking active mixed content. It is likely that many of these sites have fixed this historical problem, so we particularly encourage `ruleset` contributors to fix these `rulesets` first: - git grep -i mixedcontent src/chrome/content/rules + git grep -i mixedcontent src/chrome/content/rules ### New Rulesets @@ -232,13 +232,13 @@ Examples: If you're not sure what subdomains might exist, you can install the `Sublist3r` tool: - git clone https://github.com/aboul3la/Sublist3r.git - cd Sublist3r - sudo pip install -r requirements.txt # or use virtualenv... + git clone https://github.com/aboul3la/Sublist3r.git + cd Sublist3r + sudo pip install -r requirements.txt # or use virtualenv... Then you can to enumerate the list of subdomains: - python sublist3r.py -d example.com -e Baidu,Yahoo,Google,Bing,Ask,Netcraft,Virustotal,SSL + python sublist3r.py -d example.com -e Baidu,Yahoo,Google,Bing,Ask,Netcraft,Virustotal,SSL Alternatively, you can iteratively use Google queries and enumerate the list of results like such: @@ -252,15 +252,15 @@ Alternatively, you can iteratively use Google queries and enumerate the list of In all cases where there is a list of domains, sort them in alphabetical order starting from the top level domain at the right reading left, moving ^ and www to the top of their group. For example: - example.com - www.example.com - a.example.com - www.a.example.com - b.a.example.com - b.example.com - example.net - www.example.net - a.example.net + example.com + www.example.com + a.example.com + www.a.example.com + b.a.example.com + b.example.com + example.net + www.example.net + a.example.net ### Rule Ordering @@ -276,21 +276,21 @@ Example: ```xml ``` @@ -341,11 +341,11 @@ Avoid snapping redirects. For instance, if `https://foo.fm` serves HTTPS correct ```xml - - + + - + ``` @@ -353,20 +353,20 @@ Avoid snapping redirects. For instance, if `https://foo.fm` serves HTTPS correct ```xml - - - - - - - - - - - - - - + + + + + + + + + + + + + + ```