6. Contribute!

Lumina® is an open source project which relies on involvement from its users and supporters to assist in development, documentation, and localization. This section describes how to best assist the Lumina® Project.

6.1. Communicate

Communication is the lifeblood of any open source project, and Lumina® is no exception. The developers have attempted to create many communication options in order to present a wide variety of options for users to collaborate and contribute to the project:

Note

Due to the closeness of the two projects, Lumina® and TrueOS® share many of these communication channels. If using a shared channel, please clarify which project you are discussing.

  • Forums: A Lumina section is available on the PC-BSD® forums. Registration is required before creating a new thread.
  • GitHub: The Lumina GitHub repository has an “Issues” section for Report a Bug or requesting features. If requesting a feature, be sure the title of the issue begins with Feature Request:.
  • Gitter: Gitter is a chat option with GitHub integration. Users can use their GitHub account to sign into Gitter, and activity in an integrated repository will be displayed in a column next to the chat window.
  • IRC: The #pcbsd or #lumina-desktop channels on the Freenode IRC server are also available for collaborating with other users and the developers.
  • Mailing Lists: Visit http://lists.pcbsd.org/mailman/listinfo to view the various mailing list options. Click an option to open a page that allows you to subscribe to the list.
  • Reddit: The TrueOS® Subreddit page is available for general discussion of the Lumina® or TrueOS® projects. An account is not necessary to view topics, but is required to create new posts.
  • Weblate: Lumina® uses Weblate, an online translation tool, to translate and provide Lumina® in a variety of languages. See Become a Translator for details about translating Lumina®.
  • Website: The Lumina Website offers the latest news and updates about the project.

The Lumina® developers want your feedback about how to improve the project. Please use these communication options and let us know what you think!

6.2. Report a Bug

One of the most effective ways to assist the Lumina® Project is by reporting problems or bugs encountered while using Lumina®. Subscribing to Lumina News is a good way to keep up-to-date on the availability of new Lumina® versions.

Anyone can report a Lumina® bug. However, bug reporting should follow a few guidelines to ensure a speedy response:

  • Lumina® uses its GitHub repository, seen in Figure 6.2.1, to manage bugs. A GitHub account is required before bugs can be reported. Navigate to https://github.com, fill in the required fields, and click Sign up for GitHub to create a new github account.
_images/buga.png

Fig. 6.2.1 : Lumina Issues Tracker

Warning

The GitHub issues tracker uses email to update contributors on the status of bugs. Please use a valid and frequently used email address when creating a GitHub account for the efficient resolution of issues.

  • Use the Search bar on the Issues <https://github.com/trueos/lumina/issues>`_ section to confirm no similar bug report exists. If a similar report does exist, add any additional information to the report via a comment. While it is not required to log in to search existing bugs, adding a comment or creating a new report does require signing into the website.
  • To create a new bug report, log into the website, then navigate to https://github.com/trueos/lumina/issues. Click New Issue to open the window shown in Figure 6.2.2.
_images/bug1.png

Fig. 6.2.2 : Creating a Bug Report

  • Write a brief but descriptive title that includes the error and the version of Lumina®. Ideally, the title is short (8 words or less) and contains key words about the error so the bug report is easily found with the search tool.
  • In the Description field, write about the circumstances of the error, including instructions how to recreate it. If an error message is generated, reproduce the error in its entirety. Also, attaching a screenshot to the report can greatly aid the developer in visualizing the problem.
  • After describing the issue, click Submit new issue to create the issue. The bug tracker will attach a unique number to the report and send update messages to the creator’s registered email address whenever activity occurs with the bug report.

6.3. Become a Translator

Translating Lumina® into additional languages is extremely helpful to the developers, and very appreciated! There are two primary elements to Lumina® which need to be translated:

  1. The graphical elements within Lumina®.
  2. The Lumina® Handbook (this document).

This section describes each of these elements in more detail and how to begin participating in translating Lumina.

An excellent first step is to join the translations mailing list. After joining, send an introductory email and indicate which language(s) and which type(s) of translations you can assist with. Participating in the mailing list will keep you up to date with important changes to Lumina® and help coordinate with the other volunteers.

6.3.1. Interface Translation

Lumina® uses Weblate to manage the localization of menu screens seen in Lumina®. Weblate also efficiently displays the progress of localization efforts, allowing users to quickly find if their language is fully or partially supported in Lumina®. Furthermore, Weblate simplifies the process to check and submit translated text through its integrated web editor and commenting system. These tools allow translators to spend more of their time making and reviewing translations rather than learning how to use a complicated tool set.

To see the status of a localization, open the Lumina Weblate Project in a web browser, as seen in Figure 6.3.1.

_images/translate1b.png

Fig. 6.3.1 : The Lumina® Project Overview Screen.

Requested localizations are listed alphabetically on the left. The right columns contain information about the project and any glossaries that may be defined for the project. If the desired language is missing and you would like to help in its translation, notify the Lumina® or TrueOS® developers on Slack, Gitter, or Reddit.

The green bar in the Translated column indicates the completion percentage of the various Lumina® components. Green progress shows good translations, while yellow and red colors in the progress bar indicate translations that may need additional review. Any language not fully translated will display the incomplete menus in English.

Click on a component name to see each available language for translation. Figure 6.3.2 shows the lumina-config component. In this example, lumina-config has almost been completely translated to Bulgarian (bg), but has just begun translation to Afrikaans (af).

_images/translate2b.png

Fig. 6.3.2 : lumina-config Overview screen.

A Weblate account is necessary to edit a translation. Log in to Weblate and navigate to the desired component in need of translation. In Figure 6.3.3, the translator has clicked Translate in the lumina_CONFIG@af row.

_images/translate3b.png

Fig. 6.3.3 : Translation screen for lumina-config, Afrikaans language

In this example, the phrase “Manually set value for selection” needs to be reviewed. To edit the translation, type the translated text into the Translation text field and click Save or Suggest. There is also a Commit message field for adding a comment to the translation. To translate or review another string, press the forward or back icons at the top of the page. Additionally, Weblate generates a Nearby messages section across the bottom of the page, providing quick links to other strings needing review. On the right side of the page are several boxes providing additional information:

  • Things to check: Weblate will generate warnings about elements of the string that may need review. This box will only appear if the automatic reviewer generates an error.
  • Glossary: The glossary box can provide simple lookups to aid in translating a string, but a glossary will need to be added to the project first.
  • Source information: This box offers background information on the string: the context, location, its priority, and if it fails any of the Weblate checks.

If help is needed with a translation or general use of the Weblate system, please ask for help on the translations mailing list or in the translations forum.

6.3.2. Documentation Translation

At this time, the Lumina® Handbook has not yet been added to the translation system. Once it has, instructions for translating the Handbook will be added here.

6.4. Become a Developer

Developers who want to help improve the Lumina® codebase are always welcome! To participate in core development, please subscribe to the developers mailing list.

All Lumina® utilities are developed with C++ using Qt Libraries, but other Qt-based languages are used in the project too. For example, the CSS-like Qt Stylesheet language is used for theme templates.

6.4.1. Getting the Source Code

Lumina® uses github to store its source code.

Note

Be sure git in installed on your system prior to downloading the source code. TrueOS® includes git as part of the base install.

To download the source code, use the command line to navigate to (or create) the desired storage directory and from within the directory, type:

git clone git://github.com/trueos/lumina.git

These commands will create a directory named lumina/, which contains the local copy of the repository. Keep the local copy synchronized with the official repository by typing git pull within the lumina/ directory.

To compile the source code, start by checking the list of required software to install any needed Qt5 modules. Alternately, pkg install qt5 will install all available Qt5 modules, which ensures the system can compile the source code.

Note

The pkg system is used by FreeBSD based operating systems; other OS’s will use different packaging systems and command syntax.

Once the necessary Qt elements are installed, compile the source by typing qmake to generate a Makefile, then run make. This example is using a TrueOS® system; the binary paths may differ on other operating systems:

cd lumina

/usr/local/lib/qt5/bin/qmake

make

Note

If you encounter an issue trying to compile the source on a system other than TrueOS®, refer to the “How to build from source” section of the README for additional instructions.

To also install the compiled applications, type sudo make install. This command requires superuser privileges.

Several Qt integrated development environments (IDE) are available for development. These IDEs can be installed using AppCafe® on TrueOS® or other operating systems’ software management utilities. QtCreator is a fully featured IDE designed to help new Qt developers acclimate quickly and boost the productivity of experienced developers. Qt Designer is a lighter weight option as it includes only a .ui file editor with no other IDE functionality.

To submit changes for inclusion in Lumina®, fork the repository using the instructions in fork a repo. Make any changes to the forked repository, them submit them for inclusion in the primary Lumina® repository via a git pull request. Once the submitted changes have been reviewed, they can either be committed to the repository or returned to the creator with additional suggestions for improvement.

6.4.2. Design Guidelines

Lumina® is a project driven by the support of developers within the community. Developers have designed and implemented a number of new utilities and tools into Lumina since its inception. The project aims to present a unified design in order to retain the familiarity of most programs. For example, while programs have had the titles of “File”, “Main”, or “System” as the first entry in a menu bar, Lumina® opts to use “File”, as it is the most common option for the first category on a menu bar.

The Developer Guidelines contain some coding practices for creating effective updates or utilities. For menu and program design in Lumina®, there is a small list of guidelines volunteer developers are encouraged to follow.

Any graphical program which is a fully featured utility, such as Insight File Manager, needs a “File” menu. However, a “File” menu is not necessary for a small widget or dialogue box. When making a file menu, try to keep it very simple. Most Lumina® utilities include only two or three items in the “File” menu.

“Configure” is the Lumina® standard for the category of settings or configuration related settings. If additional categories are needed, it is recommended to look through other Lumina® utilities for common naming conventions.

File menu icons are taken from the installed icon theme. Table 6.4.1 lists some commonly used icons and their default file names.

Table 6.4.1 : Commonly Used File Menu Icons
Function File Menu Icon File Name
Quit row 1, cell 2 window-close.png
Settings row 2, cell 2 configure.png

Lumina® utilities uses several buttons:

  • Apply: Applies settings and leaves the window open.
  • Close: Closes a program without applying settings.
  • OK: Closes the dialogue window and saves settings.
  • Cancel: Closes the dialog window without applying settings.
  • Save: Saves settings and can also close the window.

Keyboard shortcuts are extremely useful to many users, and Lumina® attempts to include shortcuts in every utility. Qt simplifies assigning keyboard shortcuts. For example, configuring keyboard shortcuts to browse the “File” menu is as simple as adding &File to the menu entry’s text field during application creation. Whichever letter has the & symbol in front will become the new hotkey. A shortcut key can also be made by clicking the menu or submenu entry and assigning a shortcut key. Avoid creating duplicate hotkeys or shortcuts. Every entry in a menu or submenu should have a key assigned for accessibility. Table 6.4.2 and Table 6.4.3 summarize the commonly used shortcut and hotkeys.

Table 6.4.2 : Shortcut Keys
Shortcut Key Action
CTRL + Q Quit
F1 Help
Table 6.4.3 : Hot Keys
Hot Key Action
Alt + Q Quit
Alt + S Settings
Alt + I Import
Alt + E Export
ALT + F File Menu
ALT + C Configure Menu
ALT + H Help Menu

Developers will also find these resources helpful: