Contributing to Apps

We welcome community user contributions, issue reporting, and suggestions for new features and apps to create the best possible TrueNAS app user experience!

Application maintenance is independent of TrueNAS version release cycles. App version information, features, configuration options, and installation behavior during access might vary from those in documented tutorials.

TrueNAS apps show the Update badge and button on any deployed application instance on the Installed application screen when a new version is available. Users can apply the update(s) individually or collectively and at a convenient time based on needs.

Users can submit changes to an existing application catalogs through:

• GitHub Contributions

  We are actively working on making the core application library more user-friendly. This process might involve breaking changes to the API. Therefore, please wait for an update on when you can start submitting pull requests.

  Thank you for your understanding.

• Community Forum Feature Requests

  To request a feature change, go to the TrueNAS Community Forum, and click Feature Request. Read the About the Feature Requests category - README First topic, then click Open Draft on the top right of the screen. Populate the new request form with the relevant information for each section, Problem/Justification, Impact, and User Story. The form guides you on populating these sections. Click Create Topic to add your suggestion to the list of topics.

  Users vote and comment on these suggestions. iXsystems actively monitors this channel and discusses the feasibility of each request both internally and in the forum posts.

  If approved and requested to submit a PR to add the new application, submit a PR against the TrueNAS/Community repository. Include the relevant files in the PR, including a ReadMe.txt file with any installation notes for iXsystems developers.

To see a current list of apps, visit the TrueNAS Apps repository on GitHub.

Community members can submit change requests or add new tutorials to the Truenas Apps > Community Apps tutorials section of the Documentation Hub.

For more information on submitting change requests, forking repos, and submitting PRs, see Updating Content.

When submitting new tutorials or requesting changes to existing TrueNAS Documentation Hub application tutorials:

1. Create the PR against a forked copy of the TrueNAS Documentation Hub public repository.

2. Open the existing article file in the /content/TrueNASApps/CommunityApps directory of your local forked repository.

3. Add the new tutorial to the CommunityApps folder in your local copy of the repository if submitting a new tutorial.

4. Use the text editor of your choice to make changes to the application tutorial template as the basis for your new article. Article content is written in Commonmark Markdown.

5. (Optional) Save images in the /documentation/static/images/scale/apps folder of your local branch.

6. Submit the PR against the Master branch.

Feel free to change standard article content by adding or removing sections to fit the app installation process. Change the front matter description: parameter at the top of the article to suit the subject and content of the new tutorial. Description text must not exceed 160 alphanumeric or special characters, including spaces between characters. After updating content, delete commented-out sections providing instructions for using this template when they are no longer needed. When documenting a Community train app, not delete any of the commented-out instructions in the COMMUNITY APP INTRO SNIPPETS section.

Standard text emphasis:

• Apply Bold to UI elements seen on the screen, including field, button, and navigation option names, other descriptions, etc. Use double asterisks preceding and following the name or text string to make it bold. Do not use bold in code strings.

• Apply Italics to any variable. Use single asterisks preceding and following the name or text string to make it italics. If using a variable in a code example, use the HTML tags (<i></i>) and not the Markdown tags.

• Apply HTML file tags (<file></file>) when entering a path to a file or file name, for example <file>iso</file>, which renders as iso.

• Apply HTML keyboard tags (<kbd></kbd>) to keys on a keyboard, for example <kbd>Enter</kbd>, which renders as Enter.

When entering commands, command strings, or code blocks:

• Apply backticks(``) or HTML <code></code> tags to format command strings or output, for example `string` or <code>string</code>, which render as string.

• Apply HTML <code></code> tags to strings with variables.

  • Do not enclose variables in angle or square brackets as these can also be part of command syntax.

  • Do not enter variables in all caps unless the command requires entering the value in all caps.

To create a code block, either use three backticks (```) on the line before and after the content block, or use the HTML code tags.

When creating your articles you can use the library of snippets that contain explanations of settings and configuration instructions for the various app Install Wizard settings in your submitted content. These snippets are maintained by the Technical Documentation team, but you can submit change requests for these files just as with full articles if you find content that needs updating or changing.

The tutorial template includes the shortcode that calls these files into the app wizard sections of the Stable Apps and Enterprise Apps tutorials in the Documentation Hub. To use snippets where the template does not have one, enter the include file shortcode where you want to call another snippet. The shortcode to call snippet files is {{<include file="/static/includes/apps/snippetFileName.md">}}, where snippetFileName.md is the name of the snippet file.

The following table shows the current list of snippet files.

Click Edit Article at the top of the Documentation Hub article to suggest changes to an existing article.

Refer to the Content Updates article for more details.