Skip to content

Contributing Step by Step

Jump to bottom Edit New page
Hussam al-Homsi edited this page Jun 10, 2020 · 8 revisions

If you'd like to help develop LMMS, you've come to the right place. This guide gives an overview of the steps involved in contributing to LMMS's development, and links to useful resources for each step of the way.

The process

0. Get connected

In the #devtalk channel on the LMMS Discord, you can ask questions or discuss things related to LMMS' development.

1. Decide what you'd like to work on

Whether it's a feature or a bug fix, you'll need to know exactly how you want to improve LMMS.

  • There's lots of existing issues to choose from, and some of them are good for beginners.
  • If you know what area of LMMS you want to work on, you can check if there's a relevant meta issue and pick something from there.
  • If you've have something specific in mind and there's no existing issue for it, you can follow this guide and open an issue yourself.

2. Build your own copy of LMMS

In order to try out the changes you make, you'll want a local copy of LMMS's source code that you build yourself.

  • Decide which branch you'll work on. This can be tricky, so ask on #devtalk if you're unsure. At time of writing, master branch is the best choice.
  • Compile your working branch.

3. Set up your IDE

A most common situation is that windows is used on daily basis, but window and building LMMS, does no go hand in hand.
The solution is a virtual-LINUX-OS in a virtualBox as so called Guest in your so called Host-windows!
Oracle Virtual Box is a solid implementation.
Later we may add a guide for VBox, but one thing must be mentioned:
Most tutorial addressing LINUX in a virtual box, recommend way to little disk-space! In order to have at solid development environment for LMMS and all its dependencies, you should at least allocate 30 GB to your VBox! Oracle VBox should have dynamic disk-storage, but that has not been the case for me.

One more thing that is absolute certain: You will need to get accesses to text in both windows and linux, but you will learn, that you cant use your pc-clipboard in both OS!
Here is a trick to manage that situation:
Use a mail-account!
You can have your mail open in both OS, and then you can simply just write mails to the same mail-account
That way you have complete free access to all documents on both OS!

IDE : To be explained...

4. Familiarize yourself with the relevant code

Now it's time to find the part of LMMS' code relevant to your improvement.

5. Implement your improvement

Finally, get to work!

  • Your changes should follow the LMMS coding conventions.
    • This includes writing good comments for:
      • Any non-trivial members you add (in Doxygen format)
      • Parts of your code that may be hard for others to understand
      • Existing code you had to figure out while working on your PR
  • If appropriate, add unit tests.

6. Check your code

Check the following points to make your review pass:

  • Run the existing unit tests and make sure they pass: make tests && tests/tests.
  • Make manual tests for everything your code may have affected
    • Does the new solution work?
    • Is no old functionality destroyed?
  • Double check that you followed the coding conventions?
    • Spaces after if, else, for, while and switch are often forgotten. A quick check: git diff <base-version> | grep -v '^-' | grep '[^A-Za-z]\(if\|else\|for\|while\|switch\)('
    • Another common mistake: { and } should be alone in their code line, unless the block is closed in the same line: git diff <base-version> | grep '{' | grep -v '\${' | grep -v '^-' | grep -v '^+\?[[:space:]]*{[[:space:]]*$' | grep -v '^[^{}]*{[^{}]*}[^{}]*$'
  • If you want your PR to be be merged via a merge commit, clean up all commits with git rebase -i.
    • Commits that won't compile or that fixed previous commits should be squashed.
    • Commit messages will be visible even after merge. Change any uninformative commit messages into something significant!

7. Create a pull request ("PR") and await review

Once your changes work on your local copy, it's time to share them.

  • Create a PR.
  • Investigate CI failures on the PR webpage.
  • Label your PR if you have permission:
    • As long as it's not ready for review, use "in progress" or "needs clarification"
    • When ready for review, label as "needs code review" and "needs style review"
  • Your changes will be reviewed according to this guide. If you'd like this step to be faster, you can help out by reviewing other's PRs!

8. Celebrate!

Actually, you might get a few comments about things you have to change first. Even so, you've come a long way, so give yourself a pat on the back! Once any issues with your pull request are worked out, it can be merged and LMMS will be better for it :)

Clone this wiki locally