Skip to content

Latest commit

 

History

History
96 lines (78 loc) · 8.09 KB

usage.asciidoc

File metadata and controls

96 lines (78 loc) · 8.09 KB
Raw
Table of Contents

This section explains the usage of devonfw-ide according to your role:

  • Everybody should read and follow the usage for a developer.

  • In case you want to administrate devonfw-ide settings for your project, you should also read the usage for the ide-admin.

Usage

Developer

As a developer you are supported to setup your IDE automated and fast while you can have a nice cup of coffee (after you provided settings-URL and accepted the license). You only need the settings URL from your ide-admin. Experienced developers can directly call setup «settings-URL». Otherwise if you just call setup (e.g. by double-clicking it), you can enter it when you are prompted for Settings URL (using copy&paste to avoid typos).

Note: devonfw-ide supports autocompletion (since 2021.04.001). Currently this only works in bash (on windows use git bash). Simply type devon and hit [Tab] to get completion.

Update

To update your IDE (if instructed by your ide-admin), you only need to run the following command:

devon ide update

Please note that windows is using file-locking what can have ugly side-effects. To be safe, you should have your IDE tools shut down before invoking the above update command. E.g. if a tool needs to be updated, the old installation folder will be moved to a backup and the new version is installed on top. If there are windows file locks in place this can fail and mess up things. You can still delete the according installation from your software folder and rerun devon ide update if you ran into this error.

Working with multiple workspaces

If you are working on different branches in parallel you typically want to use multiple workspaces.

  1. Go to the workspaces folder in your ${DEVON_IDE_HOME} and create a new folder with the name of your choice (e.g. release2.1).

  2. Check out (git clone …​) the according projects and branch into that workspace folder.

  3. Open a shell in that new workspace folder (cd to it) and according to your IDE run e.g. eclipse, vscode, or intellij to create your workspace and launch the IDE. You can also add the parameter create-script to the IDE commandlet in order to create a launch-script for your IDE.

You can have multiple instances of eclipse running for each workspace in parallel. To distinguish these instances you will find the workspace name in the title of eclipse.

Admin

You can easily customize and configure devonfw-ide for the requirements of your project. In order to do so, you need to create your own project-specific settings git repository and provide the URL to all developers for the setup. With tools such as gitlab, bitbucket or github every developer can easily propose changes and improvements. However, we suggest that one team member is responsible to ensure that everything stays consistent and works. We will call this person the ide-admin of your project.

The following are the suggested step-by-step instructions how an ide-admin should prepare devonfw-ide for his new project:

  1. Fork ide-settings to a git repository specific for your project (e.g. a new project in the gitlab of your production-line instance). In case you are using github, all you need to do is use the Fork button. In other cases simply create a new and empty git repository and clone this to your machine. Then add the default ide-settings as origin, fetch and pull from it:

    git remote add upstream https://github.com/devonfw/ide-settings.git
git fetch upstream
git pull upstream master
git push

    Now you should have a full fork as a copy of the settings git repo with all its history that is ready for upstream merges.

  2. Study the structure of this git repository to understand where to find which configuration.

  3. Study the configuration and understand that general settings can be tweaked in the toplevel devon.properties file of your settings git repository.

  4. Configure the tools and their versions for your project. Here is an example:

    DEVON_IDE_TOOLS=(java mvn eclipse)
ECLIPSE_VERSION=2020-06
# use e.g. 8u242b08 for Java 8
#JAVA_VERSION=8u242b08
JAVA_VERSION=11.0.5_10
MAVEN_VERSION=3.6.2

    This way you will take over control of the tools and their versions for every developer in your project team and ensure that things get reproducible.

  5. In case you need a proprietary or unsupported tool, you can study how to include custom tools.

  6. In case you have very restrictive policies about downloading tools from the internet, you can create and configure a software repository for your project or company.

  7. Some of the tools (especially the actual IDEs) allow extensions via plugins. You can customize them to your needs for eclipse, VS code, or intelliJ.

  8. In your settings git repository you will find a projects folder. Here you will find configurations files for every git project relevant for your actual project. Feel free to create new projects for your needs and delete the devonfw specific default projects. The projects documentation will explain you how to do this.

  9. For every IDE you will also find an according folder in your settings git repository. Here are the individual configuration settings for that IDE. You can change them by directly editing the according configuration files directly with a text-editor in your settings git repository. However, this is a really complex way and will take you a lot of time to find the right file and property to tweak for your actual need. Instead we suggest to study how to customize IDE specific settings.

  10. You may also create new sub-folders in your settings git repository and put individual things according to your needs. E.g. you could add scripts for greasemonkey or tampermonkey, as well as scripts for your database or whatever may be useful and worth to share in your team. However, to share and maintain knowledge we recommend to use a wiki instead.

  11. You may want to customize the Eclipse spellchecker dictionary for your project and your language.

All described in the above steps (except the first one) can be used to manage and update the configuration during the project lifecycle. However, when you have done changes especially in a larger project, please consider the following best-practices to avoid that a large teams gets blocked by a non-functional IDE:

  • Commit your changes to a feature-branch.

  • First test the changes yourself.

  • If all works as expected, pick a pilot user of the team to test the changes from the feature branch (go to settings folder, git fetch, git checkout -t origin/feature/«name», devon ide update).

  • Only after that works well for a couple of days, inform the entire team to update.

Announce changes to your team

In order to roll out the perfectly configured devonfw-ide to your project initially or when new members join, you only have to provide the Settings URL to the developers of your team. You can also provide a specific branch with Settings URL#branch to use variations of common settings or to test new settings before making them public to the team.

After you changed and tested your settings git repository (main branch), you only need to announce this to your developers (e.g. via email or some communication tool) so that they will call devon ide update and automatically get up-to-date with the latest changes (see update).

In case you want to go to a new version of devonfw-ide itself, developers have to call devon ide update scripts.