docs/en_US/development.md

   1 ## HTTPS Everywhere Development
   2
   3 ### Pointers for developers
   4
   5 *   **License:** GPL version 3+ (although most of the code is GPL-2 compatible)
   6 *   **Source code:** Available via Git with `git clone
   7     https://github.com/EFForg/https-everywhere.git`. You can fork and open pull
   8     requests using Github at
   9     [https://github.com/EFForg/https-everywhere](https://github.com/EFForg/https-everywhere).
  10 *   **Translations:** If you would like to help translate HTTPS Everywhere into
  11     another language, you can do that [through
  12     Transifex](https://www.transifex.com/otf/torproject/).
  13 *   **Bug tracker:** Use the [GitHub issue
  14     tracker](https://github.com/EFForg/https-everywhere/issues/) or the [Tor
  15     Project issue tracker](https://trac.torproject.org/projects/tor/report/19).
  16     For the Tor Project issue tracker, you can make an account or use the
  17     anonymous one — "cypherpunks"/"writecode". You won't see replies unless you
  18     put an email address in the CC field. Bugs that are caused by rulesets
  19     should be tagged "httpse-ruleset-bug", and can be viewed [in this
  20     report](https://trac.torproject.org/projects/tor/report/48).
  21 *   **Mailing lists:** The
  22     [https-everywhere](https://lists.eff.org/mailman/listinfo/https-everywhere)
  23     list ([archives](https://lists.eff.org/pipermail/https-everywhere/)) is for
  24     discussing the project as a whole; the
  25     [https-everywhere-rules](https://lists.eff.org/mailman/listinfo/https-everywhere-rules)
  26     mailing list
  27     ([archives](https://lists.eff.org/pipermail/https-everywhere-rules)) is for
  28     discussing the [rulesets](https://www.eff.org/https-everywhere/rulesets)
  29     and their contents, including patches and git pull requests.
  30 *   **IRC:** `#https-everywhere` on `irc.oftc.net`; if you don't have an IRC
  31     client application already installed, you can [use this webchat
  32     interface](https://webchat.oftc.net/?channels=#https-everywhere). If you
  33     ask a question, be sure to stay in the channel — someone may reply a few
  34     hours or a few days later.
  35
  36 ### Testing and contributing changes to the source code
  37
  38 HTTPS Everywhere consists of a large number of rules for switching sites from
  39 HTTP to HTTPS. You can read more about how to write these rules
  40 [here](https://www.eff.org/https-everywhere/rulesets).
  41
  42 If you want to create new rules to submit to us, we expect them to be in the
  43 src/chrome/content/rules directory. That directory also contains a useful
  44 script, make-trivial-rule, to create a simple rule for a specified domain.
  45 There is also a script in test/validations/special/run.py, to check all the
  46 pending rules for several common errors and oversights. For example, if you
  47 wanted to make a rule for the example.com domain, you could run
  48
  49     bash ./make-trivial-rule example.com
  50
  51 inside the rules directory. This would create Example.com.xml, which you could
  52 then take a look at and edit based on your knowledge of any specific URLs at
  53 example.com that do or don't work in HTTPS.
  54
  55 Before submitting your change, you should test it in Firefox and/or Chrome, as
  56 applicable. You can build the latest version of the extension and run it in a
  57 standalone Firefox profile using:
  58
  59     bash ./test.sh --justrun
  60
  61 Similarly, to build and run in a standalone Chromium profile, run:
  62
  63     bash ./run-chromium.sh
  64
  65 You should thoroughly test your changes on the target site: Navigate to as wide
  66 a variety of pages as you can find. Try to comment or log in if applicable.
  67 Make sure everything still works properly.
  68
  69 After running your manual tests, run the automated tests and the fetch tests:
  70
  71     bash ./test.sh
  72
  73     bash ./fetch-test.sh
  74
  75 This will catch some of the most common types of errors, but is not a
  76 guaranteed of correctness.
  77
  78 Once you've tested your changes, you can submit them for review via any of the
  79 following:
  80
  81 *   Open a pull request at
  82     [https://github.com/EFForg/https-everywhere](https://github.com/EFForg/https-everywhere).
  83 *   Email https-everywhere-rules@eff.org to tell us about your changes. You can
  84     use the following command to create a patch file: `git format-patch`
  85
  86 ### A quick HOWTO on working with Git
  87
  88 You may want to also look at the [Git Reference](http://gitref.org/), [GitHub
  89 Help Site](https://help.github.com/) and the [Tor Project's Git
  90 documentation](https://gitweb.torproject.org/githax.git/tree/doc/Howto.txt) to
  91 fill in the gaps here, but the below should be enough to get the basics of the
  92 workflow down.
  93
  94 First, tell git your name:
  95
  96     git config --global user.name "Your Name"
  97     git config --global user.email "you@example.com"
  98
  99 Then, get a copy of the 'origin' repository:
 100
 101     git clone https://github.com/EFForg/https-everywhere.git
 102     cd https-everywhere
 103
 104 Alternatively, if you already have a Github account, you can create a "fork" of
 105 the repository on Github at
 106 [https://github.com/EFForg/https-everywhere](https://github.com/EFForg/https-everywhere).
 107 See [this page](https://help.github.com/articles/fork-a-repo) for a tutorial.
 108
 109 Once you have a local copy of the repository, create a new branch for your
 110 changes and check it out:
 111
 112     git checkout -b my-new-rules master
 113
 114 When you want to send us your work, you'll need to add any new files to the
 115 index with git add:
 116
 117     git add ./src/chrome/content/rules/MyRule1.xml
 118     git add ./src/chrome/content/rules/MyRule2.xml
 119
 120 You can now commit your changes to the local branch. To make things easier, you
 121 should commit each xml file individually:
 122
 123     git commit ./src/chrome/content/rules/MyRule1.xml
 124     git commit ./src/chrome/content/rules/MyRule2.xml
 125
 126 Now, you need a place to publish your changes. You can create a github account
 127 here: [https://github.com/join](https://help.github.com/).
 128 [https://help.github.com/](https://help.github.com/) describes the account
 129 creation process and some other github-specific things.
 130
 131 Once you have created your account and added your remote in your local
 132 checkout, you want to push your branch to your github remote:
 133
 134     git push github my-new-rules:my-new-rules
 135
 136 Periodically, you should re-fetch the master repository:
 137
 138     git pull master