mirror of
https://github.com/oxen-io/session-desktop.git
synced 2023-12-14 02:12:57 +01:00
Update README, add CONTRIBUTING
Move the development setup instructions to CONTRIBUTING.md and add some guidelines for pull requests and such. README now contains crypto export notice, license, etc... Borrowed heavily from the Signal-iOS readme.
This commit is contained in:
lilia
parent
29b2ffc769
commit
bea19e7997
2 changed files with 143 additions and 73 deletions
121
CONTRIBUTING.md
Normal file
121
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
Contibutor Guidelines
|
||||
=====================
|
||||
|
||||
## Installation and setup
|
||||
|
||||
* 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's directory
|
||||
|
||||
Note that for development, you should always be using the staging server, which
|
||||
uses a [self-signed ssl
|
||||
certificate](https://github.com/WhisperSystems/TextSecure-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 at any time you notice
|
||||
a console error about an "INSECURE RESPONSE", repeat this process.
|
||||
|
||||
Once that's done, in the extension's options page, you can register for
|
||||
TextSecure:
|
||||
|
||||
* Select "Register" under "I'm new to TextSecure".
|
||||
* 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.
|
||||
|
||||
You should now be able to use the extension. If you need to re-register, open a
|
||||
browser console within the extension options page (or inspect
|
||||
`background.html`) and execute `localStorage.clear()` to delete your account
|
||||
information.
|
||||
|
||||
## 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.
|
||||
|
||||
* 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 unfininshed 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://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
|
||||
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 motiviations 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://visionmedia.github.io/mocha/) and our assertion library is
|
||||
[chai](http://chaijs.com/api/assert/).
|
||||
|
||||
To run tests, open `test/index.html` in your browser. Note that
|
||||
|
||||
* Some tests depend on the native client module. These will fail unless you
|
||||
load the test page from the `chrome-extension://` namespace (as opposed to
|
||||
the `file://` namespace or via a local webserver.
|
||||
* Some tests may read, write or clear localStorage. It is recommended that you
|
||||
create a Chrome user profile just for running tests to avoid clobbering any
|
||||
existing account and message data.
|
||||
95
README.md
95
README.md
|
|
@ -1,87 +1,36 @@
|
|||
TextSecure Chromium Implementation
|
||||
==================================
|
||||
TextSecure for the Browser
|
||||
==========================
|
||||
|
||||
[](https://travis-ci.org/WhisperSystems/TextSecure-Browser)
|
||||
|
||||
This is very early stuff and exists primarily to get the crypto in place.
|
||||
*This does not currently work, dont bother trying to use it seriously yet*
|
||||
:warning: *This project is still in the prototype phase. It contains many bugs
|
||||
and lacks many features.*
|
||||
|
||||
Getting Started with Development
|
||||
================================
|
||||
Private text and chat for the browser.
|
||||
|
||||
These steps are for **development only**.
|
||||
## Interoperability
|
||||
|
||||
* 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's directory
|
||||
TextSecure for the Browser works with [Signal for
|
||||
iOS](https://github.com/WhisperSystems/Signal-iOS) and
|
||||
[TextSecure](https://github.com/WhisperSystems/TextSecure) on Android.
|
||||
|
||||
Note that for development, the TextSecure staging environment uses a
|
||||
self-signed certificate, which Chrome will complain is insecure. So first visit
|
||||
<https://textsecure-service-staging.whispersystems.org/> in your browser and
|
||||
allow the certificate.
|
||||
## Cryptography Notice
|
||||
|
||||
Now, in the extension's options, you can register for TextSecure:
|
||||
This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software.
|
||||
BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted.
|
||||
See <http://www.wassenaar.org/> for more information.
|
||||
|
||||
* Select "Register" under "I'm new to TextSecure".
|
||||
* 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.
|
||||
The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms.
|
||||
The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.
|
||||
|
||||
You should now be able to use the extension. If you need to reset your
|
||||
development environment, open a browser console within the extension options
|
||||
page (or inspect `background.html`) and execute `localStorage.clear()` to clear
|
||||
out the settings.
|
||||
## License
|
||||
|
||||
Dependencies
|
||||
============
|
||||
Copyright 2014 Open Whisper Systems
|
||||
|
||||
**Note**: Unless you need to make changes to dependencies, you can skip this
|
||||
section and just use the checked in versions.
|
||||
Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html
|
||||
|
||||
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://visionmedia.github.io/mocha/) and our assertion library is
|
||||
[chai](http://chaijs.com/api/assert/).
|
||||
|
||||
To run tests, open `test/index.html` in your browser. Note that
|
||||
|
||||
* Some tests depend on the native client module. These will fail unless you
|
||||
load the test page from the `chrome-extension://` namespace (as opposed to
|
||||
the `file://` namespace or via a local webserver.
|
||||
* Some tests may read, write or clear localStorage. It is recommended that you
|
||||
create a Chrome user profile just for running tests to avoid clobbering any
|
||||
existing account and message data.
|
||||
### Developers Developers Developers Developers!
|
||||
Please see
|
||||
[CONTRIBUTING.md](https://github.com/WhisperSystems/TextSecure-Browser/blob/master/CONTRIBUTING.md)
|
||||
for setup instructions and contributor guidelines.
|
||||
|
|
|
|||
Loading…
Reference in a new issue