To start developing devonfw-ide, you must first install it on your computer. Therefore simply follow the setup guide. It is important to notice that this installation gives you the latest published version of the devonfw-ide with which you can execute commands like eclipse or docker whose scripts are located inside the "${DEVON_IDE_HOME}$/scripts/command, but for committing code we use a differing folder structure. This will be addressed under Contribution.
To begin, read through the Contribution Guidelines, which you should be sure to follow.
First steps regarding forks or cloning of repos and creating branches, as well as some git commands, can be found in the first contributions guideline.
To contribute code or documentation regarding the devonfw-ide at first you need to fork the devonfw-ide repository and then you can clone your fork into the folder workspaces/main in your devonfw-ide installation.
Open git-bash in the cloned fork at workspaces/main/ide and run the following command:
git remote add upstream https://github.com/devonfw/ide.git
git fetch upstreamWhenever you want to implement a new change first do the following things:
git checkout master
git pull upstream master
git push
git checkout -b feature/«issue-id»-«brief-feature-description»Now you can do the changes, improvements, and fixes.
Once they are tested and seem to work, you can commit them (git commit -m "#«issue-id»: «description»").
If some days have passed meanwhile you should merge changes that meanwhile happened on the official ide repo:
git pull upstream masterOnce you are complete and everything is merged and comitted, you can push your local feature branch and make it a remote branch of your fork on github:
git push -u origin feature/«issue-id»-«brief-feature-description»Now you can go to https://github.com/devonfw/ide/pulls and create the pull-request (PR) from your new feature.
Therefore, please click on the right down arrow of the green button and choose Create draft pull request and then click on Draft pull request.
When the checks have completed you can check the Definition-of-Done (DoD).
Once, all checks of the DoD are addressed, you can go the the very bottom of the PR and click on Ready for review what will take the PR out of the draft mode.
FYI: If you forgot the upstream merge (git pull upstream/master) or the upstream changed again while your PR is still open, you will see This branch is out-of-date with the base branch at the bottom of your PR and can click on Update branch.
For further development and testing, it is recommended to symlink the modified scripts into your devonfw-ide installation. Alternatively, the scripts can be adapted in the installation folder and then committed to the project. For creating a contribution also check the Definition of Done (DoD).
To improve the code quality the ShellCheck is used for devonfw-ide. There is a GitHub action CI build PR for this. If this fails at the PR, you can find the error messages in the big logfile under Build project with Maven. For example, these look like this:
Running test #2: test-shellcheck
In scripts/functions line 659:
doUnzip ${1} ${target_dir}
^--^ SC2086: Double quote to prevent globbing and word splitting.
^-----------^ SC2086: Double quote to prevent globbing and word splitting.
Did you mean:
doUnzip "${1}" "${target_dir}"
For more information:
https://www.shellcheck.net/wiki/SC2086 -- Double quote to prevent globbing ...Further explanations for ShellCheck errors can be found in the ShellCheck Wiki.
Own code can also be tested with the Online ShellCheck.
ShellCheck can also be run on the local development environment. To do this, ShellCheck (win, mac) can be extracted to the program directory. For windows the path to the executable (C:\Program Files\shellcheck-stable) has to be added to the PATH environment variable (instruction). In the resource folder of the project (scripts/src/main/resources) the following command can now be executed in the git-bash:
shellcheck -x -e SC2181 setup scripts/devon scripts/environment-project scripts/functions scripts/command/*For Mac and Linux, ShellCheck is automatically called during the build process (mvn install).
Many programs have a download link that depends on the operating system.
For a new tool, create an url-updater in the updater folder in the current repository. The Name needs to be equal to the one of both the tool and the commandlet.
There are four available parent classes of url-updaters, that can be used. They mainly differentiate in the way, available versions are detected.
Note: The WebsiteUrlUpdater should not be used if other viable options are available.
The updaters use the function doAddVersion(), where the downloadUrl, OS and architecture can be specified for each version. Example
VersionIdentifiers can also be used if e.g. the downloadUrl changed after a specific version, or certain version are not indented to be available. Example
Once a day, the UpdateInitiator will run the updaters through GitHub Actions and fill the ide-URL repository with new version/tools that are identified by the Updaters.
Use an existing commandlet like HELM as a reference. Create a file with the name of the tool and put it in the folder scripts/command. The first part of the script contains the autocompletion, which should return the available parameters. Functions like setup or run or other additional functions follow. Finally, it defines which function should be executed depending on the parameter.
Use the doInstall method for the installation, which downloads the tool based on the mirrors, unpacks it if necessary and puts it in the software folder in the devonfw-ide installation:
doInstall "-" "«installation-folder»" "«tool-name»" "«tool-version»"For standard installations omit "«installation-folder»" (use the empty string arg "") what will install to ${DEVON_IDE_HOME}/software/«tool-name».
Find the license for the new tool and add the tool to the table of Third party components of the LICENSE.
If the license itself does not exist, add it to the end of the file as a new section.
The ide-settings repository allows project-specific configurations of the IDE tools. For your own settings, fork the repository, adjust the configuration and specify the repository URL during installation. Important notes on configuration and especially configuration files can be found in the configuration. In the configuration files many variables can be defined.
The following sub-sections give you some tips and tricks to boost your productivity when developing features for devonfw-ide.
With symbolic links you can use one file or folder that is located inside one directory in one or multiple other directories, without copying the whole file or folder into the other directories. The file is still only saved at the initial location, but can be accessed through the created links in a much more comfortable way. So you are actually just linked to the original file and therefore don’t have to worry about differing versions of the file in your directories. This is very helpful for testing our devonfw-ide, because e.g. the commandlets folder for testing is not the same as the commandlets folder for git-commits. Install link shell extension and follow the instructions for installation and usage first. Later on you can make symbolic links of files or folder from your "git folder" and add them into the folder in which the testing is supposed to take place:
So select the folder ${DEVON_IDE_HOME}/workspaces/ide/scripts/src/main/resources/scripts/command/ and choose Pick Link Source and then go to ${DEVON_IDE_HOME}/scripts/ delete the command folder and re-create it as symbolic link via Drop as… > Symbolic link.
Do the same also for functions, functions-core, commandlet-cli, environment-project, environment-project.bat, devon, devon.bat, autocomplete, and devon-autocomplete.
Now changes you make in the first mentioned file will directly be available in your testing environment through the created file-link in the testing environment.
Have a look at advanced-tooling-generic.asciidoc for some helpful developer tools.
For beginners:
You probably know this black box on Windows (the Command Prompt) that accepts commands like 'dir' that shows the content of the directory you are currently in, or 'cd' with which you can change the directory you are currently in and many more commands that allow you to interact with your Windows Operating System in a more direct and eventually faster way. Now for users of a Linux Distribution there is something similar, but way more powerful, usually called "Bourne Again Shell", or in short Bash. This Command Line Interface or "Shell" is what we use most often when implementing something new for our Command-Line-Tool with the name devonfw-ide. Have a look at Bash in 150 Seconds. For MacOS you often also use BASH. That’s why it is often enough to implement code for Mac or Linux (at least to some extend as you’ll see soon enough) to be able to use it on both Operating Systems.
Let’s get to the practical part of the Bash-usage.
If you are using Windows, make sure that you have git-bash installed, so you can execute the Bash commands mentioned in this introduction. [Here you can find git for windows](https://git-scm.com/download/win). In some cases later on you may want or need to use WSL. Our project teams standard way is to install WSL via Rancher Desktop, which is easily installable with the devonfw-ide by using the command devon docker setup. If you don’t have the devonfw-ide yet, then you can follow [this guide](https://github.com/devonfw/ide/blob/master/documentation/setup.asciidoc)
The following video gives you some important and helpful basics, still you don’t need to know all of these commands directly by heart. Instead under the video you’ll find a list with the commands mentioned in the video to make a command return to your mind. Also directly play around with those commands while watching the video to learn faster.
When you used to program in some other languages, you for sure know how helpful a google search in combination with the results on stackexchange can be.
If not, then google your question regarding Bash as usual and mostly you’ll find a way to get together the code you want.
Sometimes it needs more patience to get an acceptable result or to find out that a command you already knew includes what you need, if you add the proper tag to its execution.
Take the commands and some of their tags mentioned in this rather brief tutorial as an example. Also definitely try to use the help function from time to time, e.g. type in ls --help and you’ll see how much more the command ls can offer.
On the other side, especially at the beginning, it is better to get an overview of available tags by googling e.g.
ls tags Bash to get a way prettier overview plus examples regarding a commands tags like here for ls.
If you have some experience with the Bash or directly want to see more:
The meaning of a tag or a sign combination (like $*, $#, or $()) can be hard to guess and also less easy to find during a google-search, because google won’t directly search for signs.
Then a syntax cheatsheet like this or like that one can spare you some searching time.
If you don’t know what a positional parameter like $1 is in Bash, then have a look at this introduction and play around with the tools mentioned to get a better understanding of how they work.
It’s definitively worth knowing the basics about positional parameters if you want to make some more advanced Bash-scripts.
There are a few more topics that I want to mention to you as you may come across them regularly in Bash-scripting.
The first one concerns regular expressions, which you will find during various coding situations.
Therefore have a look at this rather short introduction on regex if you are unfamiliar with the so called regex.
Another one is about if-statements and square brackets for testing expressions by comparing them in different ways.
Maybe you’ll find something new or helpful here.
Finally, to possibly increase your knowledge while scripting bash-files, try out this spellchecker that can give you many details on how to improve your code.
Directly regarding our project:
In case you want to get your hands dirty with code that is already in use and comes from our ide-project, then you can try out the functions written in our functions-file. There are also some basic exercises related to our project that are not official yet, but you can ask for if you want to try some of them out to learn and challenge yourself a bit.
Scroll down on this site to get an overview of the documentation sections for the devonfw-ide, e.g. Home, Features, Download & Setup or have a look at the documentation files folder.