Skip to content

How To Contribute

Jump to bottom
Martin Večeřa edited this page Nov 26, 2023 · 11 revisions

If you want to contribute to Lumeer engine, read this document in order to save both your time and the time of developers who maintain this project.

Repository

Before you start working on this project, you will need to set up your Git repository properly. To do so, follow these steps:

  1. If you are not familiar with Git, read at least first 3 chapters of this book.
  2. Set up your Git by following these instructions.
  3. Fork Lumeer engine repository by following this guide.

IntelliJ Idea Setup

Make sure you have installed Java 21 and set it as project language level and also as a runtime environment running your Idea. Idea complaints about a couple of packages despite the fact these are in dependencies. This is How to fix it. Add --add-exports=java.desktop/sun.awt=ALL-UNNAMED --add-exports=java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.security=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.management/javax.management=ALL-UNNAMED --add-opens=java.naming/javax.naming=ALL-UNNAMED.

Code style

In order to avoid unnecessary formatting commits, all developers are required to use the same code style. You can find code style configuration files for your IDE in code-style folder.

The source code is also checked by Maven Checkstyle Plugin. Try to fix all warnings from its report when making changes in this project. Besides other things, it also controls if you add JavaDoc to your code.

License

Add the following license header at the beginning of every Java file you add to Lumeer engine repository:

/*
 * Lumeer: Modern Data Definition and Processing Platform
 *
 * Copyright (C) since 2017 Lumeer.io, s.r.o. and/or its affiliates.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

Build

Lumeer engine uses Apache Maven as a build tool. You will need to install Maven before you start working on this project.

To build this project, run the following command in Lumeer/engine folder:

mvn clean install

It will check the source code, compile the project, and run the tests.

Testing

If you add new functionality to Lumeer engine, always write the tests for it. Add unit tests for all your components as well as integration tests which run Lumeer engine with your components.

Make sure all existing tests pass when you make any changes. Never submit a pull request with failing tests.

Pull requests

Contributions to this project are merged through pull requests. They help to avoid undesirable changes to be added to the project as well as allow developers to do code reviews. Always create a pull request, even if you have direct write access to the repository.

Workflow

Follow these steps to make your contribution as smooth as possible:

  1. Update devel branch in your local repository with the latest changes from upstream:

    git checkout devel
git pull upstream devel

  2. Create a new feature branch where you will make your changes:

    git checkout -b my-branch-name

  3. Make your changes in the project.

  4. Commit your changed files.

  5. If there were any changes in the upstream branch in the meantime, update your local branch with these changes:

    git pull -r upstream devel

  6. Push the commit to your fork of Lumeer engine repository:

    git push -u origin my-branch-name

  7. Go to Lumeer engine repository and GitHub will automatically offer you an option to create a pull request from your feature branch.

If you are requested to do some changes after the code review, follow these steps:

  1. Create a new commit with additional changes.

  2. If there were any changes in the upstream branch in the meantime, update your local branch with these changes:

    git pull -r upstream devel

  3. Push your commit to your fork.

Commits

Make sure you always add only a single commit per pull request. If you have made several commits during your development process, squash them into one before sending a pull request.

However, when making changes in the pull-request after a review, it is better to make new commits. This is just for a reviewer so they can easily what has been changed. The commit will be squashed into a single one when merging the pull-request.

Write good commit messages. Keep them short and self-explanatory. If you have not read How to Write a Git Commit Message, do it right now!

Merging

You can merge a pull-request in two different ways:

  1. Squash and merge
  2. Rebase and merge

Squash and merge

Use this option if the author of a pull-request made several commits during the development process but these commits would only clutter up Git history without adding any useful information. All commits from the pull-request will be squashed into a single one.

This should be the default option if you are not sure which one to use.

Rebase and merge

Use this option if the author of a pull-request made several commits which should be kept in the Git history.

This is typically used when there are two different changes made in a pull-request where the second change depends on the first one and you want to see both changes in the Git history. For example you can do a heavy refactoring in the first commit and add a new feature in the second one.

Clone this wiki locally