Contributing

Contributing to the Code

Engine Driver is open source software written in Java for Android. The source code is available on github.com/JMRI/EngineDriver.

It is recommended that you contact M Steve Todd if you intend to contribute to the code base, before you start working.

On the Android device you intend to test on

  • Make sure that the developer options are enabled and Android debugging is on, and unknown sources is on. You can also use the Virtual Devices in Android Studio to test you code.

Here are all the steps needed for Microsoft Windows:

  • On GitHub

    • Clone the JMRI/EngineDriver repository. (See Cloning a repository in GitHub)

    • Create a Personal Access Token that will allow you remotely update your repository. See [here] for details. Copy the full code of the token somewhere as you will need it later.

  • Install Android Studio.

  • Open Android Studio
    (If necessary, close any open project and restart, so you get the Welcome Wizard)

  • Select Check out project from Version control -> Git

  • In the Clone Repository window, enter the Git Repository URL: https://github.com/JMRI/EngineDriver, -> Clone.
    Note this is the ‘origin’ repository, not your clone.

  • Open the project.

  • Only if needed…

    • Take the Run ‣ Run… ‣ Edit Configurations option

    • In the Run/Debug Configurations window, press the +, then Android App

    • Enter Name “EngineDriver”, and select Module: EngineDriver

    • Click Run.

    • You will likely get one or more error messages about missing components. Click on the link in each message and Android Studio will automatically download the missing components.

To test your changes:

  • Connect your phone via USB

  • In the Select Deployment Target window, your attached phone should show under Connected Devices.

  • Select your device and press run or debug.

  • EngineDriver should compile and be installed on your device.

To publish your changes:

  • Android Studio, commit and push your changes to your own GitHub repository..
    To do this you will need to define a new remote https://github.com/<your name>/EngineDriver

  • Go to GitHub and issue a Pull Request for your branch to be pulled into the origin repository. Once it’s merged in by one of the admins, your changes will go live!

Contributing to the Localisation (Languages)

We are always looking for people to help with maintaining and expanding the non-English versions of the text in the code.

It is possible to do so via the methods described in Contributing to the Code but if you are not a developer this can be daunting.

If you are interested in helping with this please please contact the developers and we can provide a simpler way to contribute.

Contributing to the Documentation

This documentation web site is open source and can be accessed on github.com/mstevetodd/EngineDriver_Home

All this documentation is done using reStructuredText and with Sphinx, for which you can find information on the official website: reStructuredText and the Sphinx document builder tool website. reStructuredText is a markdown type language, for typesetting documents from websites to PDF or LaTeX documents. This Website is built upon this technology, so you should make yourself familiar with this by looking through the links provided.

reStructuredText QuickReference Guide

The steps listed here provide guidance on how to edit and preview changes to the documentation.

  • You need to install a number of tools on your local machine:

    • An appropriate text editor.
      For Windows we recommend the free Visual Studio Code IDE (VSC).

    • A version of Git.
      For Windows we recommend the free GitHub Desktop.

    • A current version of ‘Python 3’ (which also installs ‘pip’).
      The Microsoft Store contains Python published by the Python Software Foundation for Windows.

  • Then use ‘pip’ to install the required packages; ‘sphinx’ and the theme ‘sphinx_rtd_theme’.
    Open and command prompt and enter:

    • pip install -r requirements.txt

  • On GitHub

    • Create an account on Github, if you don’t already have one

    • Clone the https://enginedriver.mstevetodd.com repository. (See Cloning a repository in GitHub)

    • Open your repository ‘Settings’ (the gear icon), go to the ‘Pages’ section and change the ‘Branch’ to gh-pages / (root)

    • Your repository must be public

  • On your PC

    • Using GitHub Desktop, clone your GitHub repository to your local machine

    • Edit the files in the EngineDriver_Home/docs folder (using VSCode or any text editor)

    • Save your changes (VSCode continuously saves as you type)

    • Check and preview your changes by running make github from the root of the EngineDriver_Home folder. [1]
      This must be done from cmd.exe in Windows, not PowerShell.
      If any warnings are reported, fix these and run make github again

    • Preview your changes locally by going to your local directory EngineDriver_Home/docs/_build/html and open index.html in your web browser of choice.

    • Use GitHub Desktop to Commit then Push your changes

  • In GitHub

    • You can check the ‘Actions’ to see if it built correctly.
      You can preview the pages on GitHub at https://<yourname>.github.io/EngineDriver_Home

    • Issue a pull request for your branch to be pulled into the origin repository.
      Once it’s merged in by one of the admins, your changes will go live!

Style Guidelines

  • Use British/Australian/Canadian spelling e.g. ‘colour’ not ‘color’.
    (Primarily because it is used in more English speaking countries)

  • Use railroad/railway terminology that is understandable by all English-speaking people.
    Where there are clear differences from US to non-US terminology use both with a slash between and use the US version first. e.g. turnouts/points, Consists / Multiple Units, switching/shunting. (Primarily because DCC and JMRI use the US terminology)

  • In general use ‘loco’ instead of ‘locomotive’ or ‘engine’

  • Avoid the term ‘Checked’. Use ‘Enabled’ instead. (“Checked’ is more a US term.)

  • Use bolded **Engine Driver** or |ed| not ‘Engine Driver app’, ‘EngineDriver’ or ‘Engine Driver Throttle’ (except on the first page) - Engine Driver

  • No full stop at the end of a numbered or unnumbered list

  • Numbered lists should be avoided, unless there is a specific need

  • Use second person (you and your; not I, me, or my) language

  • A string or list of nouns should be sequenced in alphabetic order, unless it makes more sense within the context to display them in some other sequence

  • Double quotes (”) should only be used for quoting text from people, documents or web sites

  • No quotes around ‘Also See’ type references

  • Avoid ‘(above)’ or ‘(below)’ in text. Use hypertext links instead

  • ‘TODO’ or |todo| or .. todo:: in the text means that it is still a work-in-process and needs to be updated. It may be followed by descriptive text in italics describing the issue to be fixed

  • Keep headings short. If it fills the page it is too long.

  • Keep sentences short. Break them up where ever possible.

  • Keep paragraphs short. Break them up where practical.

  • Keep paragraphs on the same topic. If the topic changes start a new paragraph.

  • Use ``literal text blocks`` when describing preference values - literal text blocks

  • Use :menuselection:`Menu –> Preferences –> ..` for menu descriptions - Menu ‣ Preferences ‣ ..

  • Use :guilabel:`GUI labels` for buttons - GUI labels

  • Avoid using ‘phone’ alone. Preferably use ‘Android device/phone’

  • For dates, use dd-mmm-yyyy or yyyy-mm-dd to avoid confusion with the way dates are uniquely written in the US.
    e.g. 2-Mar-2022 or 2022-3-2, not 2-3-2022

  • Heading levels:

    • ######### with overline, for parts - not really used

    • ************ Page Titles

    • ========= for sections

    • --------------- for subsections

    • ^^^^^^^^^ for subsubsections

    • """"""""""""""" for paragraphs

    • ''''''''''''''''''''''''''' for sub paragraphs

TODO

We are always looking for assistance with the improving this website. Any assistance would be greatly appreciated.

Below are areas that we know need work.

Todo

MEDIUM: Which locos in a Consist/Multiple Unit the functions are sent to

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/functions.rst, line 85.)

Todo

LOW: Maximum throttle Change Can’t remember when this is used.

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1293.)

Todo

LOW: Consist Functions - Follow Rule Style

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1385.)

Todo

LOW: Manual host specific import/export

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 2492.)

Todo

LOW: ‘Special Partial Matching’ Option

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 248.)

Todo

LOW: ‘Special’ Consist Function Matching Options

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 430.)

Todo

LOW: ‘Special - Exact Matching’ Option

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 449.)

Todo

LOW: ‘Special Partial Matching’ Option

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 459.)

Todo

LOW: ‘Special Partial - Contains Only’ Option

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 469.)

Todo

LOW: FAQ Selecting locomotives to control

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 152.)

Todo

LOW: FAQ DCC ‘Advanced Consists’ (CV19)

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 171.)

Todo

LOW: FAQ JMRI Consists

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 180.)

Todo

LOW: FAQ Direction Buttons

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 367.)

Todo

LOW: FAQ LOW: FAQ Swiping up or Down

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 390.)

Todo

LOW: FAQ Showing the web page at the bottom of the throttle screen

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 400.)

Todo

LOW: FAQ Loco selection screen

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 414.)

Todo

LOW: FAQ Locos in the roster not showing

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 424.)

Todo

LOW: FAQ Changing the turnouts screen

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 450.)

Todo

MEDIUM: FAQ DCC-EX Features

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 493.)

Todo

LOW: If you turn the gamepad off…

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/gamepads.rst, line 105.)

Todo

LOW: Web View Area (Throttle Web View)

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 495.)

Todo

MEDIUM: Select by DCC Address

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1106.)

Todo

LOW: Programming on the Main Screen

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1531.)

Todo

LOW: Children’s Timer Status and Countdown

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1899.)

Todo

LOW: Firewalls

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 40.)

Todo

MEDIUM: Disconnections

(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 84.)