Skip to content

Latest commit

 

History

History
211 lines (163 loc) · 9.12 KB

CONTRIBUTING.md

File metadata and controls

211 lines (163 loc) · 9.12 KB
Raw

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.

It's a good idea to gauge interest in your intended work by finding the current issue for it or creating a new one yourself. You can use also that issue as a place to signal your intentions and get feedback from the users most likely to appreciate your changes.

You're most likely to have your pull request accepted easily if it addresses bugs already in the Next Steps project, especially if they are near the top of the Backlog column. Those are what we'll be looking at next, so it would be great if you helped us out!

Once you've spent a little bit of time planning your solution, it's a good idea to go back to the issue and talk about your approach. We'd be happy to provide feedback. An ounce of prevention, as they say!

Developer Setup

First, you'll need Node.js which matches our current version. You can check .nvmrc in the development branch to see what the current version is. If you have nvm you can just run nvm use in the project directory and it will switch to the project's desired Node.js version. nvm for windows is still useful, but it doesn't support .nvmrc files.

Then you need git, if you don't have that yet: https://git-scm.com/

macOS

  1. Install the Xcode Command-Line Tools.

Windows

  1. Windows 7 only:
  2. Install Windows Build Tools: Open the Command Prompt (cmd.exe) as Administrator and run: npm install --global --production --add-python-to-path windows-build-tools

Linux

  1. Pick your favorite package manager.
  2. Install python
  3. Install gcc
  4. Install g++
  5. Install make
  6. Depending on your distro, you might need to install hunspell and hunspell-<lan> (e.g. hunspell-en-au)

All platforms

Now, run these commands in your preferred terminal in a good directory for development:

git clone https://github.com/loki-project/loki-messenger.git
cd loki-messenger
npm install --global yarn      # (only if you don’t already have `yarn`)
yarn install --frozen-lockfile # Install and build dependencies (this will take a while)
yarn grunt                     # Generate final JS and CSS assets
yarn icon-gen                  # Generate full set of icons for Electron
yarn test                      # A good idea to make sure tests run first
yarn start                     # Start Loki Messenger!

You'll need to restart the application regularly to see your changes, as there is no automatic restart mechanism. Alternatively, keep the developer tools open (View > Toggle Developer Tools), hover over them, and press Cmd + R (macOS) or Ctrl + R (Windows & Linux).

Also, note that the assets loaded by the application are not necessarily the same files you’re touching. You may not see your changes until you run yarn grunt on the command-line like you did during setup. You can make it easier on yourself by generating the latest built assets when you change a file. Run this in its own terminal instance while you make changes:

yarn grunt dev # runs until you stop it, re-generating built assets on file changes

Additional storage profiles

Since there is no registration for Loki Messenger, you can create as many accounts as you can public keys. To test the P2P functionality on the same machine, however, requries that each client binds their message server to a different port.

You can use the following command to start a client bound to a different port.

yarn start-multi

For more than 2 clients, you can setup additional storage profiles and switch between them using the NODE_APP_INSTANCE environment variable and specifying a new localServerPort in the config.

For example, to create an 'alice' profile, put a file called local-alice.json in the config directory:

{
  "storageProfile": "aliceProfile",
  "localServerPort": "8082",
}

Then you can start up the application a little differently to load the profile:

NODE_APP_INSTANCE=alice yarn run start

This changes the userData directory from %appData%/Loki-Messenger to %appData%/Loki-Messenger-aliceProfile.

Making changes

So you're in the process of preparing that pull request. Here's how to make that go smoothly.

Tests

Please write tests! Our testing framework is mocha and our assertion library is chai.

The easiest way to run all tests at once is yarn test.

You can browse tests from the command line with grunt unit-tests or in an interactive session with NODE_ENV=test yarn run start. The libtextsecure tests are run similarly: grunt lib-unit-tests and NODE_ENV=test-lib yarn run start. You can tweak the appropriate test.html for both of these runs to get code coverage numbers via blanket.js (it's shown at the bottom of the web page when the run is complete).

To run Node.js tests, you can run yarn test-server from the command line. You can get code coverage numbers for this kind of run via yarn test-server-coverage, then display the report with yarn open-coverage.

Pull requests

So you wanna make a pull request? Please observe the following guidelines.

  • First, make sure that your yarn ready run passes - it's very similar to what our Continuous Integration servers do to test the app.
  • Never use plain strings right in the source code - pull them from messages.json! You only need to modify the default locale _locales/en/messages.json.
  • Rebase your changes on the latest development branch, resolving any conflicts. This ensures that your changes will merge cleanly when you open your PR.
  • Be sure to add and run tests!
  • 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.
  • Avoid meaningless or too-granular commits. If your branch contains commits like the lines of "Oops, reverted this change" or "Just experimenting, will delete this later", please squash or rebase those changes away.
  • 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 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.

Above all, spend some time with the repository. Follow the pull request template added to your pull request description automatically. Take a look at recent approved pull requests, see how they did things.

Testing Production Builds

To test changes to the build system, build a release using

yarn generate
yarn build-release

Then, run the tests using grunt test-release:osx --dir=release, replacing osx with linux or win depending on your platform.