166 lines
7.4 KiB
Markdown
166 lines
7.4 KiB
Markdown
Contributor Guidelines
|
|
======================
|
|
|
|
## Advice for new contributors
|
|
|
|
Start small. The PRs most likely to be merged are the ones that make small,
|
|
easily reviewed changes with clear, and specific intentions. See below for more
|
|
[guidelines on pull requests](#pull-requests).
|
|
|
|
Stick to issues that are
|
|
[on the roadmap](https://github.com/WhisperSystems/Signal-Desktop/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22On+the+roadmap%22).
|
|
Issues that are not included in this milestone may be not yet triaged,
|
|
unplanned, or not actionable for one reason or another.
|
|
|
|
If you start working on an issue, leave a comment to let others know. It is
|
|
also a good idea to outline your approach to the problem in order to get
|
|
feedback.
|
|
|
|
## Installation
|
|
|
|
* Clone the repo
|
|
* Open Chrome
|
|
* Go to chrome://extensions/
|
|
* Enable developer mode (checkbox on the top right)
|
|
* Click "Load unpacked extension..."
|
|
* Point to the repo directory
|
|
|
|
## Developer Setup
|
|
|
|
For development, you should always be using the staging server.
|
|
Registrations on the staging server are completely partitioned from the
|
|
production server that the mobile apps use. A production app from the Play
|
|
store or iTunes is hard-coded to connect to the production server. If you wish
|
|
to pair your phone and computer, or test sending between the browser and
|
|
mobile, **you must build a mobile client that targets the staging server**
|
|
(see below, under
|
|
[Linking](#linking)).
|
|
|
|
**Important!** The staging server uses a [self-signed ssl
|
|
certificate](https://github.com/WhisperSystems/Signal-Browser/issues/110).
|
|
By default, your browser will reject this certificate as insecure. Therefore,
|
|
in order to register or send and receive messages of any kind, you must first
|
|
visit <https://textsecure-service-staging.whispersystems.org/> in a new tab and
|
|
click through the warnings to allow the certificate. If done successfully,
|
|
you should get a 404 from the server. If at any time in the future you notice
|
|
a console error about an "INSECURE RESPONSE" or "Handshake was canceled",
|
|
repeat this step.
|
|
|
|
## Linking
|
|
|
|
Currently only the Android client supports multi-device linking.
|
|
|
|
0. Build Signal for Android from source, and change its `TEXTSECURE_URL` to point
|
|
at `textsecure-service-staging.whispersystems.org`. This task is 1% search and
|
|
replace, 99% [setting up your build environment](https://github.com/WhisperSystems/Signal-Android/blob/master/BUILDING.md).
|
|
1. Upon installing the extension you will be presented with a qr code.
|
|
2. On your phone, open Signal and navigate to Settings > Devices. Tap the "+"
|
|
button and scan the qr code.
|
|
3. Click through the confirmation dialog on the phone.
|
|
4. The browser will display your phone number and device name. Edit the device
|
|
name if desired. Click ok and wait for setup to complete. Key generation can
|
|
take up to a minute.
|
|
|
|
## Standalone Registration
|
|
**NOTE:** This is only for developers and will not be presented to users.
|
|
|
|
* Open the background page and run the following command in the console: `extension.install("standalone")`.
|
|
* Enter a real phone number (Google Voice numbers work too) and country
|
|
combination and choose to send an SMS. You will receive a real SMS.
|
|
* Enter the verification code you received by SMS.
|
|
* Wait for key generation to complete.
|
|
|
|
You should now be able to use the extension.
|
|
|
|
## Chrome profiles
|
|
|
|
Don't have any friends to help you test the extension? Make a couple of Chrome
|
|
profiles. Each one will need its own Google account and Google Voice number.
|
|
Each one will have to repeat the setup process documented above, including
|
|
re-accepting the staging server cert under each profile. This is a tedious
|
|
process, but once you are done you will be able to send messages back and forth
|
|
between different profiles, allowing you to observe both endpoints of a
|
|
conversation.
|
|
|
|
## Pull requests
|
|
|
|
So you wanna make a pull request? Please observe the following guidelines.
|
|
|
|
* Please do not submit pull requests for translation fixes. Anyone can update
|
|
the translations in
|
|
[Transifex](https://www.transifex.com/projects/p/signal-desktop).
|
|
* Always localize your strings. Signal Desktop uses the
|
|
[chrome.i18n infrastructure](https://developer.chrome.com/extensions/i18n)
|
|
for localization. You **only** need to modify the default locale
|
|
[`_locales/en/messages.json`](_locales/en/messages.json). Other locales are
|
|
generated automatically based on that file and then periodically uploaded to
|
|
Transifex for translation.
|
|
* Rebase your changes on the latest master branch, resolving any conflicts
|
|
that may arise. This ensures that your changes will merge cleanly when you
|
|
open your PR.
|
|
* Run the tests locally by opening the test page in your browser. A
|
|
test-breaking change will not be merged.
|
|
* Make sure the diff between our master and your branch contains only the
|
|
minimal set of changes needed to implement your feature or bugfix. This will
|
|
make it easier for the person reviewing your code to approve the changes.
|
|
Please do not submit a PR with commented out code or unfinished features.
|
|
* Don't have too many commits. If your branch contains spurious commits along
|
|
the lines of "Oops, reverted this change" or "Just experiementing, will
|
|
delete this later", please squash or rebase those changes out.
|
|
* Don't have too few commits. If you have a complicated or long lived feature
|
|
branch, it may make sense to break the changes up into logical atomic chunks
|
|
to aid in the review process.
|
|
* Provide a well written and nicely formatted commit message. See [this
|
|
link](http://chris.beams.io/posts/git-commit/)
|
|
for some tips on formatting. As far as content, try to include in your
|
|
summary
|
|
1. What you changed
|
|
2. Why this change was made (including git issue # if appropriate)
|
|
3. Any relevant technical details or motivations for your implementation
|
|
choices that may be helpful to someone reviewing or auditing the commit
|
|
history in the future. When in doubt, err on the side of a longer
|
|
commit message.
|
|
|
|
## Dependencies
|
|
|
|
**Note**: Unless you need to make changes to dependencies, you can skip this
|
|
section and just use the checked in versions.
|
|
|
|
Dependencies are managed by [bower](http://bower.io) and built with
|
|
[grunt](http://gruntjs.com). To change them, you'll need to install node and
|
|
npm, then run `npm install` to install bower, grunt, and related plugins.
|
|
|
|
### Adding a bower component
|
|
|
|
Add the package name and version to bower.json under 'dependencies' or `bower
|
|
install package-name --save`
|
|
|
|
Next update the "preen" config in bower.json with the list of files we will
|
|
actually use from the new package, e.g.:
|
|
```
|
|
"preen": {
|
|
"package-name": [
|
|
"path/to/main.js",
|
|
"directory/**/*.js"
|
|
],
|
|
...
|
|
}
|
|
```
|
|
If you'd like to add the new dependency to js/components.js to be included on
|
|
all html pages, simply append the package name to the concat.app list in
|
|
`bower.json`. Take care to insert it in the order you would like it
|
|
concatenated.
|
|
|
|
Now, run `grunt` to delete unused package files and build `js/components.js`.
|
|
|
|
Finally, stage and commit changes to bower.json, `js/components.js`,
|
|
and `components/`. The latter should be limited to files we actually use.
|
|
|
|
## Tests
|
|
Please write tests! Our testing framework is
|
|
[mocha](http://mochajs.org/) and our assertion library is
|
|
[chai](http://chaijs.com/api/assert/).
|
|
|
|
To run tests, use `grunt dev` or `grunt connect watch` to spin up a local
|
|
webserver, then point your browser to localhost:9999/test/index.html and
|
|
localhost:9999/libtextsecure/test/index.html
|