Skip to content

Commit 96d4fe6

Browse files
jshajsha
committed
Update and reorganize README.
Add an install-dev-dependecies script instead of instructions, describes branching structure, and emphasizes Getting Started instructions.
1 parent 6107a55 commit 96d4fe6

File tree

3 files changed

+88
-65
lines changed

3 files changed

+88
-65
lines changed

‎README.md‎

Lines changed: 67 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,80 @@
11
HTTPS Everywhere [![Build Status](https://travis-ci.org/EFForg/https-everywhere.svg?branch=master)](https://travis-ci.org/EFForg/https-everywhere)
22
================
33

4-
Source Tree
5-
-----------
4+
Getting Started
5+
---------------
66

7-
This is the source tree for HTTPS Everywhere for Firefox and Chrome.
7+
Get the packages you need and install a git hook to run tests before push:
88

9-
Important directories you might want to know about
9+
bash install-dev-dependencies.sh
1010

11-
src/ The Firefox source
11+
Run the tests for the Firefox version:
1212

13-
chromium/ The Chromium/Chrome source
14-
(not to be confused with Firefox browser "chrome" or UI)
13+
bash test.sh
1514

16-
src/components |
17-
src/chrome/content | Firefox JavaScript and XUL code
18-
src/chrome/content/code |
15+
Run the latest code and rulesets in a standalone Firefox profile:
1916

20-
src/chrome/content/rules The rulesets live here
17+
bash test.sh --justrun
18+
19+
Run the latest code and rulesets in a standalone Chromium profile:
20+
21+
bash run-chromium.sh
2122

23+
Build the Firefox extension as a .xpi package:
2224

23-
Installing Dependencies in Debian or Ubuntu
24-
-------------------------------------------
25+
bash makexpi.sh
2526

26-
sudo apt-get install python-lxml python-libxml2 libxml2-utils sqlite3 zip
27+
Build the Chromium extension as a .crx package:
2728

28-
Installing Dependencies in Mac OS X
29-
-----------------------------------
29+
bash makecrx.sh
3030

31-
We recommend Mac users install dependencies using Homebrew:
32-
http://brew.sh/
31+
Both of the build commands store their output under pkg/.
3332

34-
Once you have Homebrew and Xcode installed, run this to install HTTPS Everywhere dependencies.
33+
Precommit Testing
34+
-----------------
35+
36+
One can run the available test suites automatically by enabling the precommit
37+
hook provided with:
38+
39+
ln -s ../../hooks/precommit .git/hooks/pre-commit
3540

36-
brew install python libxml2 gnu-sed
41+
Source Tree
42+
-----------
43+
44+
This is the source tree for HTTPS Everywhere for Firefox and Chrome.
45+
46+
Important directories you might want to know about
3747

38-
Homebrew puts python in /usr/local/bin, but the python that comes with OS X is in /usr/bin. In order to use homebrew's version of python and pip you must change the order of your path so that /usr/local/bin comes before /usr/bin. This command will force your path to start with /usr/local/bin:
48+
src/ The Firefox source
3949

40-
echo PATH=/usr/local/bin:$PATH >> ~/.profile
50+
chromium/ The Chromium/Chrome source
51+
(not to be confused with Firefox browser "chrome" or UI)
4152

42-
After running this close your terminal and then open it again. Then install lxml using pip.
53+
src/components |
54+
src/chrome/content | Firefox JavaScript and XUL code
55+
src/chrome/content/code |
4356

44-
pip install lxml
57+
src/chrome/content/rules The rulesets live here
4558

4659
Hacking on the Source Code
4760
--------------------------
4861

49-
Please work off of the "3.5" branch if you're submitting changes to the latest stable release and use "master" if you're submitting changes to the latest development release.
62+
The current stable release series is 4.0. The current development release series
63+
is 5.0. Each release series is represented by a branch with the major and minor
64+
version numbers, e.g. 4.0 or 5.0. This branch is updated during the lifecycle of
65+
the release series. Specific releases are represented as tags with the full
66+
version number, e.g. 4.0.0 or 5.0development.0.
67+
68+
If you are making a bug fix to the current stable release, you should
69+
work off of the stable branch, 4.0. If you are adding features or improving
70+
functionality, work off of master. The maintainers will merge master into the
71+
development series branch periodically. We will also occasionally merge ruleset
72+
fixes from master into the stable branch if the ruleset is important (i.e. a
73+
popular or high-security site), or if the version in stable is clearly broken.
74+
75+
To submit changes, either use pull requests on GitHub or email patches to
76+
https-everywhere-rulesets@lists.eff.org (rulesets) or
77+
https-everywhere@lists.eff.org (code).
5078

5179
### Writing rulesets
5280

@@ -56,9 +84,9 @@ If you want to create new rules to submit to us, we expect them to be in the src
5684

5785
sh ./make-trivial-rule example.com
5886

59-
inside the rules directory. This would create Example.com.xml, which you could then take a look at and edit based on your knowledge of any specific URLs at example.com that do or don't work in HTTPS. You could then run
87+
inside the rules directory. This would create Example.com.xml, which you could then take a look at and edit based on your knowledge of any specific URLs at example.com that do or don't work in HTTPS. You should then run
6088

61-
python ../../../../utils/trivial-validate.py
89+
bash test.sh
6290

6391
to make sure that your rule is free of common mistakes.
6492

@@ -68,41 +96,24 @@ If you would like to help translate HTTPS Everywhere into another language, you
6896

6997
### Bug trackers and mailing lists
7098

71-
We currently have two bug trackers. The one on Github (https://github.com/EFForg/https-everywhere/issues) is recommended because it gets checked more frequently and has a friendlier user interface. The one on trac.torproject.org (https://trac.torproject.org/projects/tor/report/19) has a large backlog of bugs at this point, but it has the advantage of allowing you to post bugs anonymously using the "cypherpunks" or "writecode" account. (Note that you won't see replies unless you put an email address in the CC field.)
99+
We currently have two bug trackers. The one on Github (https://github.com/EFForg/https-everywhere/issues) is recommended because it gets checked more frequently and has a friendlier user interface. The one on trac.torproject.org (https://trac.torproject.org/projects/tor/report/19) has a large backlog of bugs at this point, but it has the advantage of allowing you to post bugs anonymously using the "cypherpunks" / "writecode" account. (Note that you won't see replies unless you put an email address in the CC field.)
72100

73101
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.
74102

75-
Build Instructions
76-
------------------
77-
78-
To build the Firefox version go to the git repository root and run:
79-
80-
./makexpi.sh
81-
82-
To build the Chrome version go to the git repository root and run:
83-
84-
./makecrx.sh
85-
86-
After building the extension the xpi files (for Firefox) and crx files (for Chrome) get created in the pkg directory. You can open those files within your browser to install the browser extension.
87-
88-
To construct ruleset file in Windows use `./utils/merge-rulesets.js`
89-
90-
Running Extension Tests
103+
Tests
91104
-------------
92105

93-
See [this README](https-everywhere-tests/README.md).
106+
There are some very basic unittests under https-everywhere-tests/. These are run with
94107

95-
Ruleset Tests
96-
-------------
108+
bash test.sh
97109

98-
You can run ruleset tests by opening `about:config` and changing `extensions.https_everywhere.show_ruleset_tests` to true. Now when you open the HTTPS Everywhere context menu there will be a "Run HTTPS Everywhere Ruleset Tests" menu item.
110+
We need a lot more tests and welcome additions.
99111

100-
When you run the tests, be prepared to let your computer run them for a really long time.
112+
There are also ruleset tests, which aim to find broken rulesets by actually
113+
loading URLs in a browser and watching for Mixed Content Blocking to fire.
114+
You can run ruleset tests by opening [about:config](about:config) and changing
115+
`extensions.https_everywhere.show_ruleset_tests` to true. Now when you open
116+
the HTTPS Everywhere context menu there will be a "Run HTTPS Everywhere Ruleset Tests"
117+
menu item.
101118

102-
Precommit Testing
103-
-----------------
104-
105-
One can run the available test suites automatically by enabling the precommit
106-
hook provided with:
107-
108-
ln -s ../../hooks/precommit .git/hooks/pre-commit
119+
When you run the tests, be prepared to let your computer run them for a really long time.

‎https-everywhere-tests/README.md‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,10 @@
11
# Tests for HTTPS Everywhere
22

33
## Prerequisites
4-
* Latest release of the Firefox Add-On SDK: https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Installation
4+
* Latest release of the Firefox Add-On SDK as a submodule:
5+
git submodule update
56

6-
## Instructions
7-
### First time
8-
1. Create a clean Firefox profile and install HTTPS Everywhere.
9-
2. Copy the profile to `./test_profile` (TODO: make this configurable).
10-
11-
### Every time
12-
1. Activate the Add-on SDK.
13-
2. cd to your HTTPS Everywhere repository root and run `./test.sh`.
7+
# Running
8+
bash test.sh
149

1510
To add tests, put them in `./https-everywhere-tests/tests`.

‎install-dev-dependencies.sh‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#!/bin/bash -ex
2+
# Install packages that are necessary and/or useful to build and debug
3+
# HTTPS Everywhere
4+
set -o errexit -o xtrace
5+
if type apt-get >/dev/null ; then
6+
sudo apt-get install libxml2-dev python-dev \
7+
firefox chromium-browser zip sqlite3
8+
elif type brew >/dev/null ; then
9+
brew install python libxml2 gnu-sed
10+
if ! echo $PATH | grep -ql /usr/local/bin ; then
11+
echo '/usr/local/bin not found in $PATH, please add it.'
12+
fi
13+
fi
14+
pip install --user -r requirements.txt
15+
16+
# Install a hook to run tests before pushing.
17+
ln -s ../test.sh .git/hooks/pre-push

0 commit comments

Comments
 (0)