CONTRIBUTING.md

Contributing

We use GitHub to maintain this initiative. First you will need a GitHub account and Git. If you are interested to use an IDE, there are IDEs which Elektra developers currently use, e.g.:

• CLion with a tutorial
• Visual Studio Code with a tutorial

Configure Git

$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"

When you connect to a GitHub repository from Git, you have to set up the authentication settings.

Check out our guide on Git for more details

Fork & Sync

We use a fork/sync and pull-request (see below) model at GitHub, follow this short tutorial to get familiar with forking and syncing.

Sync the fork of the repository to keep it up-to-date with the upstream repository by using the following git commands in your local repository. Important: Using these commands will avoid unnecessary merge commits while you are working on a pull-request (see below):

$ git fetch upstream
$ git rebase upstream/master
$ git push origin master --force

Issues

Check the Ideas page if you are searching for a good topic to start with. You can also visit the issue-tracker and filter the list by pre-defined labels like good first issue. Do not hesitate to open a new issue if you want to ask a question, report or fix a bug or approach new topics.

Ways to Contribute

• If you want to contribute to existing plugins, or create new ones, like validators, check out the tutorial at how to write plugins.
• Check out how you can contribute to make Elektra work in your favorite language: Language Bindings, Tutorial on Language Bindings.
• Improve the reliability of Elektra, by creating new, and improve existing tests. Check out the Code Coverage Report. You can also create tests for tutorials

Creating a Pull-Request

If you want to publish your local changes to this project you have to create a new pull-request. (4, 5 and 7 is Elektra-specific)

1. Open GitHub and navigate to your libelektra-fork
2. In the tab Code, click on Contribute and press the Open pull request button, then choose a title and fill in the pull-request template
3. Now you should be able to set up the Comparing changes settings. Choose the head repository and base repository. E.g.: if you have some changes in the master branch of your forked repository, select head repository: yournickname/libelektra and compare: master and base repository: ElektraInitiative/libelektra and base: master
4. Add some information about the changes in the release notes (path of the file: /libelektra/doc/news/_preparation_next_release.md), skipping this step may cause a rejected pull-request
5. Do not forget to format your code, otherwise the build server fails instantly. Take a look at the coding guidelines for more information. We provide scripts for automatically formatting various types of files. The easiest way is to run the scripts inside a Docker container.
6. Commit and push your local changes in Git (keep in mind to sync your fork - fetch, rebase & push)
7. Ask others to review (GitHub's auto-suggested reviewers often are a good start)

Code-Review

After creating the pull-request, your code will be reviewed by other developers. If your pull-request passes the review and the build server accepts your changes, they will be merged into the master branch.

Automated build doesn't pass? Don't worry... there are many reasons why the build server could fail. Open your created pull-request in GitHub and scroll to the bottom of the page, there should be a list of all checks - by clicking on Details, you get more information about the checks. There are, however, also cases where the websites are down, build server gets stuck or times-out etc., please get also an overview of the build server to avoid frustration and long review times.

General

We recommend that you read:

• The big picture what Elektra is
• The tutorials to get some practice
• The Documentation Guidelines

Code

Before you issue a pull request that modifies code:

• You should read the coding document.
• Make sure you fulfilled the checklist.

Architecture

Before you start making fundamental changes:

• You should read the design document.
• Create a decision describing what you want to do to keep the discussion more efficient and architecture documented.

Labels

• If you do not want your PR to be merged, please label the PR with the label "work in progress".
• If you included changes after a review and you think you are ready, please tag your PR with the label "ready to merge". Note that you probably also need to (re-)requests review.