Contributing to the Turtl project

Thanks for your interest in helping build Turtl! Turtl is an open-source project owned and operated by Lyon Bros. Enterprises, LLC..

Sign the Contributor License Agreement

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:

Help us code

Our central Github issue tracker covers all of the Turtl projects.

We have marked a list of items in our issue tracker you can help with!

This includes all items with the help-wanted 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 help-wanted.

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 help wanted list!

Translations

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 existing translations.

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 latest language template file to a new file with the format <language code>_<locale code>.js (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 es_mx.js.

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 sign the CLA before new translations can be accepted.

Project coding conventions

Please review the programming conventions used for Turtl’s various projects before you spend time writing code.

Javascript

These conventions apply to the following projects:

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 camelCasing it’s probably not going to be a big deal.

  • 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 i18next.t("Delete") in javascript and {{t "Delete"}} 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:

    // 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');
    

    In other words, when calling i18next.t() in javascript or {{t ...}} in handlebars, please only use literal strings!

  • Whitespace: Please use readable whitespace.

    Examples:

    // 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,
    };
    
  • Variable declarations: var-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:

    // 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);
    
  • 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:

    // 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'
    };
    
  • Underscores: use_underscores instead of camelCasing. The exception is when defining top-level classes, which use CapitalCamelCasing.

    Example:

    // 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() ...
    

Third-party libraries

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).

Rust

Our Rust code follows the standard Rust conventions, but I’ll list some of the bigger ones here:

  • 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.

  • Use underscores: No camelCase. This is a hard rule.

    Examples:

    // good
    fn get_data() -> u32 {
      0
    }
    
    // bad
    fn thisIsNotJava(orCSharp: u32) -> { ... }
    

Questions

If you have questions on any of the above, or run into a situtation that isn’t covered, please reach out to us!