signalk-server

<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Contributing | Signal K</title><meta name="description" content="Documentation for Signal K"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css?cache=1750891486567"/><link rel="stylesheet" href="../assets/highlight.css?cache=1750891486567"/><script defer src="../assets/main.js?cache=1750891486567"></script><script async src="../assets/icons.js?cache=1750891486567" id="tsd-icons-script"></script><script async src="../assets/search.js?cache=1750891486567" id="tsd-search-script"></script><script async src="../assets/navigation.js?cache=1750891486567" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js?cache=1750891486567" id="tsd-hierarchy-script"></script><link rel="stylesheet" href="../assets/theme.css"/></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title"><img src="../assets/logo.svg" alt="Signal K"/></a><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg><span class="visible@s">Search</span></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><div id="tsd-toolbar-links"><a href="https://discord.gg/uuZrwz4dCS" target="_blank" rel="noopener" class="toolbar-icon visible@s" aria-label="Discord"><svg width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><path d="M524.5 69.8a1.5 1.5 0 0 0 -.8-.7A485.1 485.1 0 0 0 404.1 32a1.8 1.8 0 0 0 -1.9 .9 337.5 337.5 0 0 0 -14.9 30.6 447.8 447.8 0 0 0 -134.4 0 309.5 309.5 0 0 0 -15.1-30.6 1.9 1.9 0 0 0 -1.9-.9A483.7 483.7 0 0 0 116.1 69.1a1.7 1.7 0 0 0 -.8 .7C39.1 183.7 18.2 294.7 28.4 404.4a2 2 0 0 0 .8 1.4A487.7 487.7 0 0 0 176 479.9a1.9 1.9 0 0 0 2.1-.7A348.2 348.2 0 0 0 208.1 430.4a1.9 1.9 0 0 0 -1-2.6 321.2 321.2 0 0 1 -45.9-21.9 1.9 1.9 0 0 1 -.2-3.1c3.1-2.3 6.2-4.7 9.1-7.1a1.8 1.8 0 0 1 1.9-.3c96.2 43.9 200.4 43.9 295.5 0a1.8 1.8 0 0 1 1.9 .2c2.9 2.4 6 4.9 9.1 7.2a1.9 1.9 0 0 1 -.2 3.1 301.4 301.4 0 0 1 -45.9 21.8 1.9 1.9 0 0 0 -1 2.6 391.1 391.1 0 0 0 30 48.8 1.9 1.9 0 0 0 2.1 .7A486 486 0 0 0 610.7 405.7a1.9 1.9 0 0 0 .8-1.4C623.7 277.6 590.9 167.5 524.5 69.8zM222.5 337.6c-29 0-52.8-26.6-52.8-59.2S193.1 219.1 222.5 219.1c29.7 0 53.3 26.8 52.8 59.2C275.3 311 251.9 337.6 222.5 337.6zm195.4 0c-29 0-52.8-26.6-52.8-59.2S388.4 219.1 417.9 219.1c29.7 0 53.3 26.8 52.8 59.2C470.7 311 447.5 337.6 417.9 337.6z"></path></svg></a><a href="https://github.com/SignalK/signalk-server" target="_blank" rel="noopener" class="toolbar-icon visible@s" aria-label="Discord"><svg width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3 .3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5 .3-6.2 2.3zm44.2-1.7c-2.9 .7-4.9 2.6-4.6 4.9 .3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3 .7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3 .3 2.9 2.3 3.9 1.6 1 3.6 .7 4.3-.7 .7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3 .7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3 .7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg></a><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="../Developing.html">Developing</a></li><li><a href="" aria-current="page">Contributing</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="contributing" class="tsd-anchor-link">Contributing<a href="#contributing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1><p>Signal K server is an Open Source project and contributions are welcome.</p> <p>Contributions are made by creating Pull Requests in the <a href="https://github.com/SignalK/signalk-server">GitHub repository</a>.</p> <p><em><strong>Working on your first Pull Request?</strong></em></p> <p>You can learn how from this <em>free</em> series <a href="https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github">How to Contribute to an Open Source Project on GitHub</a></p> <hr> <h3 id="running-the-development-server" class="tsd-anchor-link">Running the development server<a href="#running-the-development-server" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ol> <li> <p>Clone the repository:</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">clone</span><span class="hl-1"> </span><span class="hl-2">https://github.com/SignalK/signalk-server</span><br/><span class="hl-3">cd</span><span class="hl-1"> </span><span class="hl-2">signalk-server</span> </code><button type="button">Copy</button></pre> </li> <li> <p>Install dependencies:</p> <pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span> </code><button type="button">Copy</button></pre> </li> <li> <p>Build the server and related packages:</p> <pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">build:all</span> </code><button type="button">Copy</button></pre> </li> <li> <p>Start the server:</p> <pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">start</span> </code><button type="button">Copy</button></pre> </li> </ol> <p>The server should now be available at <a href="http://localhost:3000">http://localhost:3000</a>.</p> <p>As you work on your changes, you may need to re-build changes. To continuously watch for changes, open a new terminal and run <code>npm run watch</code> in either the project root, or from the relevant directory in <code>packages/*</code>.</p> <p>You may also need to restart the server to see some changes reflected.</p> <h3 id="using-sample-data" class="tsd-anchor-link">Using sample data<a href="#using-sample-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Start the server with sample data by running:</p> <ul> <li>NMEA0183 sample data: <code>bin/nmea-from-file</code></li> <li>NMEA2000 sample data: <code>bin/n2k-from-file</code></li> </ul> <p>This will start the server with a sample configuration file and the server will start playing back data from a sample file under <code>samples/</code>. The data is available immediately via the REST interface at <a href="https://localhost:3000/signalk/v1/api/">https://localhost:3000/signalk/v1/api/</a>.</p> <p>This small demo shows how to connect the Signal K Server WebSocket interface from the command line:</p> <pre><code><span class="hl-1">npm install </span><span class="hl-5">-</span><span class="hl-1">g wscat2</span><br/><span class="hl-1">wscat </span><span class="hl-2">'ws://localhost:3000/signalk/v1/stream?subscribe=all'</span> </code><button>Copy</button></pre> <h3 id="submitting-a-pull-request-pr" class="tsd-anchor-link">Submitting a Pull Request (PR)<a href="#submitting-a-pull-request-pr" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Before you submit your Pull Request (PR) consider the following guidelines:</p> <ol> <li> <p><a href="https://help.github.com/articles/fork-a-repo/">Fork</a> the repository.</p> </li> <li> <p>Make your changes in a new git branch:</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">checkout</span><span class="hl-1"> </span><span class="hl-3">-b</span><span class="hl-1"> </span><span class="hl-2">my-fix-branch</span><span class="hl-1"> </span><span class="hl-2">master</span> </code><button type="button">Copy</button></pre> </li> <li> <p>Create your patch.</p> </li> <li> <p>Commit your changes using a descriptive commit message that follows the <a href="https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits">conventions outlined here</a>. 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.</p> <ul> <li>The subject line should be in the format <code><type>: <subject></code>, where <code><type></code> should be one of: <ul> <li>feat (feature)</li> <li>fix (bug fix)</li> <li>docs (documentation)</li> <li>style (formatting, missing semi colons, ...)</li> <li>refactor</li> <li>test (when adding missing tests)</li> <li>chore (maintain)</li> </ul> </li> <li><code><subject></code> should use imperative, present tense: "change" not "changed" or "changes"</li> <li>Examples of good Subject Lines: <ul> <li><code>doc: clarify meta.units behaviour</code></li> <li><code>chore: update keyswithmetadat.json</code></li> <li><code>style: whitespace</code></li> <li><code>fix: allow nextPoint to be an intermediate leaf</code></li> <li><code>feature: push design object fields under value/values</code></li> </ul> </li> <li>Message body should also be in imperative, present tense and <strong>include motivation for the change</strong> and <strong>differences to previous behaviour</strong>.</li> <li>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".</li> <li>Subject, Body and Footer are separated by a blank line.</li> </ul> </li> <li> <p>Push your branch to GitHub:</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">push</span><span class="hl-1"> </span><span class="hl-2">origin</span><span class="hl-1"> </span><span class="hl-2">my-fix-branch</span> </code><button type="button">Copy</button></pre> </li> <li> <p>In GitHub, create a pull request.</p> </li> </ol> <ul> <li>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.</li> <li>If we suggest changes to your PR we expect you to: <ul> <li> <p>Implement the agreed changes.</p> </li> <li> <p>Rebase your branch and force push to your GitHub repository (this will update your Pull Request):</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">rebase</span><span class="hl-1"> </span><span class="hl-2">master</span><span class="hl-1"> </span><span class="hl-3">-i</span><br/><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">push</span><span class="hl-1"> </span><span class="hl-3">-f</span> </code><button type="button">Copy</button></pre> </li> </ul> </li> </ul> <h4 id="after-your-pull-request-is-merged" class="tsd-anchor-link">After your pull request is merged<a href="#after-your-pull-request-is-merged" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p>After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:</p> <ul> <li> <p>Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">push</span><span class="hl-1"> </span><span class="hl-2">origin</span><span class="hl-1"> </span><span class="hl-3">--delete</span><span class="hl-1"> </span><span class="hl-2">my-fix-branch</span> </code><button type="button">Copy</button></pre> </li> <li> <p>Check out the master branch:</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">checkout</span><span class="hl-1"> </span><span class="hl-2">master</span><span class="hl-1"> </span><span class="hl-3">-f</span> </code><button type="button">Copy</button></pre> </li> <li> <p>Delete the local branch:</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">branch</span><span class="hl-1"> </span><span class="hl-3">-D</span><span class="hl-1"> </span><span class="hl-2">my-fix-branch</span> </code><button type="button">Copy</button></pre> </li> <li> <p>Update your master with the latest upstream version:</p> <pre><code class="shell"><span class="hl-0">git</span><span class="hl-1"> </span><span class="hl-2">pull</span><span class="hl-1"> </span><span class="hl-3">--ff</span><span class="hl-1"> </span><span class="hl-2">upstream</span><span class="hl-1"> </span><span class="hl-2">master</span> </code><button type="button">Copy</button></pre> </li> </ul> </div></div><div class="col-sidebar"><div class="page-menu"><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#running-the-development-server"><span>Running the development server</span></a><a href="#using-sample-data"><span>Using sample data</span></a><a href="#submitting-a-pull-request-pr"><span>Submitting a <wbr/>Pull <wbr/>Request (<wbr/>PR)</span></a></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">Signal K</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>