CINXE.COM

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Contributing to Turtl | Turtl</title> <meta name="description" content="The safe way to remember everything. Take all your important data with you."> <link rel="stylesheet" href="/css/main.css?v=10"> <link rel="canonical" href="https://turtlapp.com/contributing/"> <link rel="alternate" type="application/rss+xml" title="Turtl" href="https://turtlapp.com/feed.xml" /> <link rel="shortcut icon" href="/images/favicon.png" type="image/x-icon"> <link href="https://fonts.googleapis.com/css?family=Lato|Noto+Serif|Slabo+13px" rel="stylesheet"> <script src="/js/mootools-core-1.6.0.js"></script> <script src="/js/mootools-more-1.6.0.js"></script> <script src="/js/composer.js?v=10"></script> <script src="/js/bluebird.min.js?v=10"></script> <script src="/js/sexhr.js?v=10"></script> <script src="/js/uikit.min.js?v=10"></script> <script src="/js/uikit-icons.min.js?v=10"></script> <script src="/js/main.js?v=10"></script> <script src="/js/stripe.js?v=10"></script> <script src="/js/controller-sig.js?v=10"></script> <script>const stripe_pubkey = 'pk_live_61JSZue0As9lbGB2CZK0DSRU';</script> </head> <body class=""> <div class="main-nav-container"> <div class="uk-container"> <nav class="main" uk-navbar> <a class="uk-navbar-item uk-logo uk-margin-right" href="/"><img src="/images/logo.svg">Turtlbeta</a> <ul class="uk-navbar-nav uk-visible@s"> <li><a href="/download">Download</a></li> <li><a href="/premium">Premium</a></li> <li> <a href="#">About</a> <div class="uk-navbar-dropdown" uk-dropdown="offset: 0"> <ul class="uk-nav uk-navbar-dropdown-nav"> <li><a href="/docs">Documentation</a></li> <li><a href="/contributing">Contributing</a></li> <li><a href="/faq">FAQ</a></li> <li><a href="/features">Features</a></li> </ul> </div> </li> <li><a href="/contact">Contact</a></li> </ul> <div class="uk-navbar-right uk-visible@m"> <ul class="uk-navbar-nav"> <li><a title="Twitter" href="https://twitter.com/turtlapp" uk-icon="icon: twitter"></a></li> <li><a title="Turtl Community" href="https://community.turtlapp.com/" uk-icon="icon: users"></a></li> <li><a title="Github" href="https://github.com/turtl" uk-icon="icon: github"></a></li> </ul> </div> <div class="uk-navbar-right uk-hidden@s"> <a class="uk-navbar-item" href="#mobile-nav" uk-toggle></a> </div> <div id="mobile-nav" uk-offcanvas> <div class="uk-offcanvas-bar"> <a class="uk-offcanvas-close"></a> <ul class="uk-nav"> <li><a href="/">Home</a></li> <li><a href="/download">Download</a></li> <li><a href="/premium">Premium</a></li> <li class="uk-parent"> About <ul class="uk-nav-sub"> <li><a href="/docs">Documentation</a></li> <li><a href="/contributing">Contributing</a></li> <li><a href="/faq">FAQ</a></li> <li><a href="/features">Features</a></li> </ul> </li> <li><a href="/contact">Contact</a></li> </ul> <ul class="uk-iconnav uk-flex-center uk-padding-small"> <li><a title="Twitter" href="https://twitter.com/turtlapp" uk-icon="icon: twitter; ratio: 1.5"></a></li> <li><a title="Turtl Community" href="https://community.turtlapp.com/" uk-icon="icon: users; ratio: 1.5"></a></li> <li><a title="Github" href="https://github.com/turtl" uk-icon="icon: github; ratio: 1.5"></a></li> </ul> </div> </div> </nav> </div> </div> <div id="container" class="uk-offcanvas-content"> <div class="uk-section"> <div class="uk-container uk-container-small"> <div class="documentation"> <h1 class="no_toc" id="contributing-to-the-turtl-project">Contributing to the Turtl project</h1> <div class="toc uk-card uk-card-default uk-card-body uk-align-right@s uk-width-1-3@s"> <ul id="markdown-toc"> <li><a href="#sign-the-contributor-license-agreement" id="markdown-toc-sign-the-contributor-license-agreement">Sign the Contributor License Agreement</a></li> <li><a href="#help-us-code" id="markdown-toc-help-us-code">Help us code</a></li> <li><a href="#translations" id="markdown-toc-translations">Translations</a></li> <li><a href="#project-coding-conventions" id="markdown-toc-project-coding-conventions">Project coding conventions</a> <ul> <li><a href="#javascript" id="markdown-toc-javascript">Javascript</a></li> <li><a href="#rust" id="markdown-toc-rust">Rust</a></li> </ul> </li> <li><a href="#questions" id="markdown-toc-questions">Questions</a></li> </ul> </div> Thanks for your interest in helping build Turtl! Turtl is an open-source project owned and operated by <a href="https://lyonbros.com">Lyon Bros LLC</a>. <h2 id="sign-the-contributor-license-agreement">Sign the Contributor License Agreement</h2> In order for us to accept your contributions to the Turtl project, you need to read and agree to the Contributor License Agreement. You can find the agreements here: <ul> <li><a href="/contributing/icla">Individual Contributor License Agreement</a> For individuals wanting to contribute</li> <li><a href="/contributing/ecla">Entity Contributor License Agreement</a> If you are contributing code as a member of a company, organization, or other entity, have someone from your organization who makes legal decisions sign this form.</li> </ul> <h2 id="help-us-code">Help us code</h2> Our central <a href="https://github.com/turtl/tracker/issues">Github issue tracker</a> covers all of the Turtl projects. We have marked <a href="https://github.com/turtl/tracker/issues?q=is%3Aissue+is%3Aopen+milestone%3A%2A+label%3Astatus%3Ahelp-wanted">a list of items in our issue tracker you can help with</a>! This includes all items with the <code class="language-plaintext highlighter-rouge">help-wanted</code> tag that are a part of one of our milestones. There are some issues that are very core to the app and require intimate knowledge of its inner workings, and these are generally not marked with <code class="language-plaintext highlighter-rouge">help-wanted</code>. Please ask before working on issues that do not have a milestone as these are generally meant to track ideas that haven’t been fully realized or “maybe” features that we want to consider but haven’t decided to include yet. Once again, if you work on issues that are not part of a milestone, chances are your PR will be rejected. When in doubt, pull issues off the <a href="https://github.com/turtl/tracker/issues?q=is%3Aissue+is%3Aopen+milestone%3A%2A+label%3Astatus%3Ahelp-wanted">help wanted list</a>! <h2 id="translations">Translations</h2> Would you like to translate Turtl to your language? Thanks for helping out! We love being multi-lingual. First, check if someone has already started translating in your language by looking through the <a href="https://github.com/turtl/js/tree/master/locales">existing translations</a>. If there’s one for your language/locale already, feel free to make any updates to the file and submit a pull request. If you language/locale isn’t there, copy the <a href="https://github.com/turtl/js/blob/master/locales/locale.js.template">latest language template file</a> to a new file with the format <code class="language-plaintext highlighter-rouge"><language code>_<locale code>.js</code> (if your language doesn’t have a specific locale code, just use the language code again). For example, a Spanish translation in the Mexican locale would be <code class="language-plaintext highlighter-rouge">es_mx.js</code>. Now just fill in what you can and submit a pull request on Github! Keep in mind that translations are significant contributions, and therefor you must <a href="#sign-the-contributor-license-agreement">sign the CLA</a> before new translations can be accepted. <h2 id="project-coding-conventions">Project coding conventions</h2> Please review the programming conventions used for Turtl’s various projects before you spend time writing code. <h3 id="javascript">Javascript</h3> These conventions apply to the following projects: <ul> <li><a href="https://github.com/turtl/js">js</a></li> <li><a href="https://github.com/turtl/android">android</a></li> <li><a href="https://github.com/turtl/desktop">desktop</a></li> <li><a href="https://github.com/turtl/browser-extension">browser-extension</a></li> </ul> Let’s go over the basics. Note that some of these rules are more loosely enforced than others. If you make a significant contribution that works beautifully but you used <code class="language-plaintext highlighter-rouge">camelCasing</code> it’s probably not going to be a big deal. <ul> <li> Localized string literals: Turtl is a multi-lingual application, and uses user-submitted translations. We build the localization template by parsing our own UI code. What this means is that we specifically look for <code class="language-plaintext highlighter-rouge">i18next.t("Delete")</code> in javascript and <code class="language-plaintext highlighter-rouge">{{t "Delete"}}</code> in our templates, and we add the string “Delete” to the translation template. This means that you cannot put the string literals into variables! For instance: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// good var title = i18next.t('Edit note'); // good var title = action == 'add' ? i18next.t('Add note') : i18next.t('Edit note'); // bad! we won't be able to parse this var key = 'Edit note'; var title = i18next.t(key); // bad! we won't be able to parse this var title = i18next.t(action == 'add' ? 'Add note' : 'Edit note'); </code></pre></div> </div> In other words, when calling <code class="language-plaintext highlighter-rouge">i18next.t()</code> in javascript or <code class="language-plaintext highlighter-rouge">{{t ...}}</code> in handlebars, please only use literal strings! </li> <li> Whitespace: Please use readable whitespace. Examples: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// fine function test(arg1, arg2) { ... } // fine (dropped braces are OK) if(condition) { ... } // one-line functions are also fine var cb = function(err, res) { ... }; // nope. please use readable whitespace function test(arg1,arg2){ } // nope. use whitespace! var obj = { key:val1, key:val2, }; </code></pre></div> </div> </li> <li> Variable declarations: <code class="language-plaintext highlighter-rouge">var</code>-per-declaration is the preferred method, but if this is against your normal style, that’s ok. One thing that will not be tolerated is leading commas. Examples: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// good var my_data = get_some_data(); var success = send_some_data(data); // if you must. var my_data = get_some_data(), success = send_some_data(data); // Not allowed (leading commas, ugh) var my_data = get_some_data() , success = send_some_data(data); </code></pre></div> </div> </li> <li> Trailing commas: Either leave them at the end of the line on the last item or take the trailing comma off. Do NOT put the comma before the item. Examples: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// good (trailing comma on last item is great A+++) var obj = { name: 'andrew', hates: 'leading commas', seriously: 'do not do it', }; // good (no trailing comma on last item also fine) var obj = { name: 'slappy', friends: 0 }; // NO. never. var obj = { name: 'andrew' , hates: 'leading commas' , seriously: 'your code will be roundly rejected' }; </code></pre></div> </div> </li> <li> Underscores: <code class="language-plaintext highlighter-rouge">use_underscores</code> instead of <code class="language-plaintext highlighter-rouge">camelCasing</code>. The exception is when defining top-level classes, which use <code class="language-plaintext highlighter-rouge">CapitalCamelCasing</code>. Example: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// good var user_settings = (new User()).get_settings(); // good (defining a top-level class) const User = Composer.Model.extend({...}); // nope var userSettings = ...; // nope function getAllNotes() ... </code></pre></div> </div> </li> </ul> <h4 id="third-party-libraries">Third-party libraries</h4> Turtl strives to use as little third-party code as possible in its front-end clients. The reason for this is that each library that is included has to be vetted for possible security leaks. For this reason, if you do feel a third-party library would suit the project, please note this in your pull request. Put your third-party libraries directly into the source tree and version them. If the third-party library makes any kind of AJAX calls, form posts, writes any scripts to <head>, or makes any other outbound connection, there is a very good chance your changes will not be merged. Dependency management tools like bower/npm/etc are not to be used or included in the javascript-based projects. Note that we do use npm to power some aspects of the build system (lessc, handlebars, postcss, etc) but under no cirumcstances does it download code to be included in the app itself. Please note that third-party libraries included in Turtl cannot be licensed copyleft (eg, GPLv3). This prevents us from relicensing Turtl, for instance if we want to release an app in the Apple iOS store. MIT/BSD licenses are strongly favored, but others will be considered on a case-by-case basis. Please make sure any third-party code you include contains the license it uses in its source file(s). <h3 id="rust">Rust</h3> Our Rust code follows the standard Rust conventions, but I’ll list some of the bigger ones here: <ul> <li> Indent with two spaces: Please follow this. All of our code uses two-space indendation and if you use tabs or four spaces or anything else, you will be asked to re-tab. </li> <li> Use underscores: No camelCase. This is a hard rule. Examples: <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// good fn get_data() -> u32 { 0 } // bad fn thisIsNotJava(orCSharp: u32) -> { ... } </code></pre></div> </div> </li> </ul> <h2 id="questions">Questions</h2> If you have questions on any of the above, or run into a situtation that isn’t covered, please <a href="/contact">reach out to us</a>! </div> </div> </div> </div> <footer class="uk-section uk-section-small uk-section-secondary"> <div class="uk-container"> <div class="uk-flex uk-flex-middle uk-flex-between@m uk-flex-wrap"> <div class="uk-width-1-3@s uk-text-center uk-padding uk-text-left@s"> Copyright © <a href="https://lyonbros.com/">Lyon Bros LLC</a> Homepage photo credits: <ul> <li><a target="_blank" href="https://unsplash.com/photos/aV5xrpB0bwQ">Soragrit Wongsa</a></li> <li><a target="_blank" href="https://www.pexels.com/photo/tortoise-on-rock-914794/">Jose Aragones</a></li> <li><a target="_blank" href="https://www.pexels.com/photo/working-in-a-group-6224/">Kaboompics.com</a></li> </ul> </div> <div class="uk-flex uk-flex-left uk-flex-space-between uk-flex-wrap uk-width-1-3@s"> <ul class="uk-nav uk-nav-default uk-width-1-2"> <li><a href="/download">Downloads</a></li> <li><a href="/premium">Premium</a></li> <li><a href="/docs">Documentation</a></li> <li><a href="/contributing">Contributing</a></li> </ul> <ul class="uk-nav uk-nav-default uk-width-1-2"> <li><a href="/contact">Contact</a></li> <li><a href="/privacy">Privacy</a></li> <li><a href="/terms">Terms</a></li>  </ul> </div> <ul class="uk-iconnav uk-flex-center uk-width-1-3@s uk-padding"> <li><a title="Twitter" href="https://twitter.com/turtlapp" uk-icon="icon: twitter; ratio: 1.5"></a></li> <li><a title="Turtl Community" href="https://community.turtlapp.com/" uk-icon="icon: users; ratio: 1.5"></a></li> <li><a title="Github" href="https://github.com/turtl" uk-icon="icon: github; ratio: 1.5"></a></li> </ul> </div> </div> </footer>  <script type="text/javascript"> var _paq = _paq || []; /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ _paq.push(['trackPageView']); _paq.push(['enableLinkTracking']); (function() { var u="//killtheradiostats.nfshost.com/"; _paq.push(['setTrackerUrl', u+'piwik.php']); _paq.push(['setSiteId', '12']); var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s); })(); </script> <noscript><img src="//killtheradiostats.nfshost.com/piwik.php?idsite=12&rec=1" style="border:0;" alt="" /></noscript>   </body> </html>