LibrePCB Developers Documentation
General Information for Developers

Table of Contents

This page contains some general information for LibrePCB developers. Please also read our contribution guidelines: https://github.com/LibrePCB/LibrePCB/blob/master/CONTRIBUTING.md

Unstable Version

As explained in the Release Workflow, the master branch is always unstable. And unstable doesn't mean "If you have bad luck, something doesn't work as expected". It rather means "Everything you save with an unstable version can't be opened again with any other (stable or unstable) version!!!". So it's highly recommended to use a dedicated workspace for testing purposes, then the files in your productive workspace are safe. When working with real projects or libraries, make a backup first or at least use a version control system so any modifications can be reverted afterwards. This can also be achieved by setting the environment variable LIBREPCB_WORKSPACE to the workspace you want to use. If you use QtCreator, this variable can be set in the run configuration, so that this workspace is only used when starting LibrePCB from within QtCreator.

Unstable application versions show a warning message box on every startup to protect users from (accidentally) beaking their files (for example if they are trying out a nightly build). For developers this message box is very annoying, so you can set the environment variable LIBREPCB_DISABLE_UNSTABLE_WARNING=1 to disable it. This variable can also be set in the run configuration, so the warning is only disabled when starting LibrePCB from within QtCreator, similar to the one above. But be careful with the disabled warning! :)

Git

  • The master branch must always compile and all tests have to pass (CI successful).
  • Use separate branches to fix bugs or implement new features.
  • Do not pack lot of changes in one commit. Make small, incremental commits instead.
  • Write commit messages according this guideline: http://chris.beams.io/posts/git-commit/

Pull Requests

To keep our Git history clear, simple and consistent, we use the following strategy for working with branches and GitHub Pull Requests:

  • If a branch is outdated (i.e. commits were added to master in the mean time), the branch should be updated by rebasing it. Please do not update branches by merging master into it (as the "Update Branch" button on the GitHub UI unfortunately does).
  • When adding fixes or other new changes to a branch, the already pushed commits should be updated accordingly (e.g. modified or amended) and then force-pushed instead of adding new commits.

Generally it's fine to deviate from these rules as long as the branch gets updated and cleaned up before it is ready to merge. But keep in mind that LibrePCB maintainers might not do a detailed review before it is cleaned up, since reviewing a clean Git history is easier.

If you are not familiar enough with Git to do the rebasing operations - no problem! LibrePCB maintainers can help you in several ways:

  • Explain you how to do the rebase operations, force-pushes etc.
  • Take over your branch and do the rebase on our own, if you agree.
  • For smaller changes, we might simply squash-merge a Pull Request.

Internationalization (i18n)

  • All files (*.cpp, *.h, *.md, *.lp, *.ini,...) must be written in english. Only strings which are visible in the GUI should be translatable into other languages.
  • Always use international date/time formats in files:
  • All numbers which are stored in files (e.g. S-Expressions or INI) must have a locale-independent format. We always use the point '.' as decimal separator, and no thousands separator. Example: 123456789.987654321

Licenses

  • All 3rd-party modules and source code (e.g. from the internet) must be compatible with the GNU GPLv3 license. This applies to all kinds of resources (images, symbols, text, sound, source code, ...).

Deployment