Contributing

Signal K server is an Open Source project and contributions are welcome.

Contributions are made by creating Pull Requests in the GitHub repository.

Working on your first Pull Request?

You can learn how from this free series How to Contribute to an Open Source Project on GitHub

Running the development server

1. Clone the repository:

   git clone https://github.com/SignalK/signalk-server
   cd signalk-server
   Copy

2. Install dependencies:

   npm install
   Copy

3. Build the server and related packages:

   npm run build:all
   Copy

4. Start the server:

   npm start
   Copy

The server should now be available at http://localhost:3000.

As you work on your changes, you may need to re-build changes. To continuously watch for changes, open a new terminal and run npm run watch in either the project root, or from the relevant directory in packages/*.

You may also need to restart the server to see some changes reflected.

Using sample data

Start the server with sample data by running:

• NMEA0183 sample data: bin/nmea-from-file
• NMEA2000 sample data: bin/n2k-from-file

This will start the server with a sample configuration file and the server will start playing back data from a sample file under samples/. The data is available immediately via the REST interface at https://localhost:3000/signalk/v1/api/.

This small demo shows how to connect the Signal K Server WebSocket interface from the command line:

npm install -g wscat2
wscat 'ws://localhost:3000/signalk/v1/stream?subscribe=all'
Copy

Submitting a Pull Request (PR)

Before you submit your Pull Request (PR) consider the following guidelines:

1. Fork the repository.

2. Make your changes in a new git branch:

   git checkout -b my-fix-branch master
   Copy

3. Create your patch.

4. Commit your changes using a descriptive commit message that follows the conventions outlined here. Whilst we are not 100% strict about this, it really helps when reviewing the PR and in making the commit history readable. The TL;DR of it is below.

   • The subject line should be in the format <type>: <subject>, where <type> should be one of:
     • feat (feature)
     • fix (bug fix)
     • docs (documentation)
     • style (formatting, missing semi colons, ...)
     • refactor
     • test (when adding missing tests)
     • chore (maintain)
   • <subject> should use imperative, present tense: "change" not "changed" or "changes"
   • Examples of good Subject Lines:
     • doc: clarify meta.units behaviour
     • chore: update keyswithmetadat.json
     • style: whitespace
     • fix: allow nextPoint to be an intermediate leaf
     • feature: push design object fields under value/values
   • Message body should also be in imperative, present tense and include motivation for the change and differences to previous behaviour.
   • Footer should reference any issues. If the PR should close issue(s) (assuming it is committed), use closes/fixes or resolves and the issue number. eg. "closes #18", "fixes #21 and resolves #23".
   • Subject, Body and Footer are separated by a blank line.

5. Push your branch to GitHub:

   git push origin my-fix-branch
   Copy

6. In GitHub, create a pull request.

• Use the same guidelines as commit messages to write the PR title and description. The server's release notes are automatically generated from PR titles, so think about how you can make them informative and easy to understand. The description should tell how the change affects the server's behavior and motivation for doing the change.
• If we suggest changes to your PR we expect you to:

  • Implement the agreed changes.

  • Rebase your branch and force push to your GitHub repository (this will update your Pull Request):

    git rebase master -i
    git push -f
    Copy

After your pull request is merged

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

• Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

  git push origin --delete my-fix-branch
  Copy

• Check out the master branch:

  git checkout master -f
  Copy

• Delete the local branch:

  git branch -D my-fix-branch
  Copy

• Update your master with the latest upstream version:

  git pull --ff upstream master
  Copy