With IDEasy we are trying our best to bring great tools to developers seamless and easy. So as a tool vendor you should try to see us as your friend helping you to reach more users and making your tool more famous.
With this page, we want to make a plea to you, dear tool vendor, to follow some best-practices to make integration smooth. This will not only make our lives easier but also help any other similar tool like SDKMAN and also end-users still trying to install tools manually. The following sections and sub-sections contain the best-practices that would be lovely to be followed by all great tools.
Even though it should be common sense how to do configuration- and release-management we learned that a lot of tools, including famous tools used world-wide, do violate such common sense.
First of all a reasonable tool should either be entirely platform independent or offer binary releases for all major platforms. A minimum requirement for major platforms should be:
-
Windows on x86 architecture
-
MacOS on ARM architecture
-
Linux on x86 architecture
Additional platforms like MacOS on x86 and Windows on ARM would also be lovely to have if you want your tool to be used worldwide. Do not leave your users left in the rain saying "build the release from the source-code" without shipping ready to use binaries! Nowadays platforms like github and others make it easy to automate cross platform builds and publishing releases with the click of a button. Tools that tell MacOS users to build the binary manually from the source-code (with complex and maybe vague instructions) should not be considered premium.
Just to give an example Python is a tool that does not offer binary releases for Linux and makes users to build it from the sources. However, worth to mention is that they are continously improving and already added binaries for MacOS what is a great progress.
If a version of a tool has been released, the download link of that tool for a particular OS and architecture should be stable and consistent.
With stable we mean that at any point of time in the future you will get the same binary file downloaded for this URL. You will not get a different binary at any time nor a 404 or 500 (except maybe in case of a short temporary technical problem).
With consistent we mean that the URL has a logical structure and could also be build from a pattern with the following variables filled in:
-
${version}- the exact version of the release (same for all platforms) -
${os}- the operating system (ideally usingwindows,mac, orlinux) -
${arch}- the architecture (ideally usingx86orarm) -
${edition}- the optional edition (if the tool comes in different editions like e.g.communityorenterprise).
We have seen a lot of anti-patterns in this regards:
-
Tools using a computed hash in the download URL that cannot be derived from the variables above. If you really think this is necessary for some reason then please provide some URL fulfilling the requirements above that redirects to the actual URL containing the magic hash.
-
Tools using a symbolic version like
latestfor the latest version. While it is a nice feature to have some URL always pointing to the latest version (e.g. via some automatic redirect) it is a severe anti-pattern to only have the latest release available under some static link that changes its content and therefore the hash of the binary download. Please understand that we compute SHA-256 hashes of your binaries centrally and IDEasy verifies this after download for security to prevent man-in-the-middle attacks. Therefore the same URL for a dedicated combination of the above parameters must always result in the same binary. -
Tools using totally different conventions for the download URL depending on operating system or other parameters.
-
Tools that had a CVE and the vendors thought it would be smart to replace an already published binary release with a modified one with the CVE being fixed. Thanks that you are fixing CVEs! That is great! But please follow best-practices and common sense and publish them as a new release with a new unique and increased version.
-
Tools that have been published and then after some time the download disappeared leading to errors like 404
We really do not want to dicatate anything regarding your versioning scheme. There are many contradicting philosophies like semantic versioning or date/timestamp based versioning, etc. However, as common sense we expect the following best-practices for a reasonable tool:
-
Comparable version numbers - given two different versions it must always be possible to say which one is lower and which one is higher. We have invested a lot of hard work for edge-cases like
4.0.0-beta2 > 4.0.0-alpha3or for Java that uses strange versions with21_35 < 21.0.2_13 < 21.0.3_9. -
Consistently mark unstable versions - please use officially agreed development phases like
alpha,beta,test[*],rc/release-candidateto mark unstable or less stable versions correctly.
Again we have seen anti-patterns here:
-
Tools using code-names for mandatory version semantic. So if you have
1.0-Waterand1.0-Carbonas versions your project team may internally know if theWaterrelease was before theCarbonrelease or vice-versa. As we cannot know, all we can do is falling back to alphabetical comparison. So if you think it is a cool idea to use code-names for relelase planning either omit them in the released version and just use them for fun and marketing or if you include them please use them only as an additional redundant information (e.g.1.0-Waterand1.1-Carbonbut never two releases with the same digits but different code-names). -
Tools using development phases in regional languages (e.g. Polish or Chinese) or using cryptic shortcuts like
uthat for one tool stands forupdateso do not use it forunstablein your tool. -
Tools including artificial parts to versions like a
vorverprefix (e.g. node prints its version as something likev19.7.0). While we can cope with this, it is generally a bad idea. -
Tools changed their versioning scheme on the go. So when you have published releases
2020.01and2021.06do not think that it is a good idea to then switch to semantic versioning and publish a4.0.1.17release. How can we determine that this is newer than any of the previous versions?
We would even love to see more semantic in your versions so end-users can distinghuish security fixes, bugfixes and new feature releases and think it will be beneficial for your tool. However, we do not directly suffer or get blocked so only those minimal requirements discussed above are what we need.
Your tool may be installed in a location with restricted permissions. Do not write to the installation location of your tool when using the tool! In general most great tools like java, dotnet, etc. are following the principle of a pristine tool installation.
First of all it is a security best-practice that a tool should not modify itself and write to its installation location. However, in the early days of computers nobody was thinking about the Internet and Hackers. Also, for arbitary reasons we introduced the concept of a shared software repository what is a powerful feature giving many advantages and on Windows seems to be the only reasonable way to allow upgrading/downgrading tools without hitting the famous Windows file locking error. Another important aspect is to consider the sandbox principle of IDEasy.
A challenge are tools that support plugins as these are typically "installed" inside the installation itself.
However, if project A installs plugin P1 for tool T then project B should not automatically get plugin P1 if it also uses tool T (in the same version).
As a tool vendor designing a plugin concept please consider the possiblity to relocate the folder where plugins are managed e.g. via a CLI option.
We solved this for the IDEs we support by a dedicated plugins folder inside the projects and relocation of the plugins for a tool into such dedicated project specific folder via some launch parameter or configuration. Beside some edge-cases (see #224) this is also solved and working for the products we support.
If your tool is a foundation like a runtime or SDK that other tools are build on top and require as a dependency then please allow that such tools can be installed separated from your tool.
Tools that are widely used but do not support this principle are:
These tools have their package manager as an individual tool with its own release cycles that lives inside the runtime of the tool itself. Even worse, other tools from their ecosystem installed via the package manager are also installed inside the runtime installation itself violating the principle of a pristine software installation. You end up with a "big ball of mud" where many different libraries and tools get mixed up in the same installation. How do you deal with two dependent tools that require different versions of the SDK (e.g. Python or node)? How do you update something if all is mixed inside this "big ball of mud" (what files to remove and replace and what to keep untouched)?
Let us assume that project P1 and P2 both want to use the latest version of node and therefore share the same installation on your computer.
Now if P1 and P2 have different requirements for the version of npm we have a conflict that cannot be resolved.
If P1 installs npm version V1 or P2 installs npm version v2 one will override the other version causing undesired side-effects.
You get exactly the same problem when you replace node with python and npm with pip.
It gets even worse if you install additional tools and libraries (e.g. npm install -g @angular/cli or pip install urllib3).
Tools typically can take parameters and options.
Please consider best practices from POSIX, GNU, IEE, and Open Group (e.g. see here) from the start.
Most CLIs violate such rules for no good reason.
As an example distinguish between short options (-h, -v, -q, -f) that typically can be combined (-qf for -q -f) and long-options (--help or --version).
Also a good convention is the end options argument (--) that e.g. allows you to delete an accidentally created file named -f in bash (via rm -- -f).
Every tool should have the CLI option to print its version via -v or --version.
Please note that Java used to have -version instead of --version but later added support also for the latter (thanks guys!).
Further, invoking this feature should printing the version number and nothing else.
Please consider that often you need to make a choice on a version in a shell script and tool vendors make life for this use-case unneccesary hard if they print lots of other information alongside.
If you want to do this add an extra option (e.g. --verbose --version) for this but never print it when -v was given as only argument.
So this is great:
$ npm -v
9.6.0While this is not perfect:
$ mvn -v
Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: D:\projects\mmm\software\mvn
Java version: 17.0.11, vendor: Eclipse Adoptium, runtime: D:\projects\salog\software\java
Default locale: en_US, platform encoding: UTF-8
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
$ docker -v
Docker version 25.0.4-rd, build c4cd0a9The worst is wsl that does not offer any option to get the version or reliably figure out if WSL1 or WSL2 is installed.
Awesome tools also have a build in help printed if -h or --help or help is given as argument.
We do not have any requirements on this but end-users will love this if they do not have to do a web-search to figure out the CLI options and then may find the wrong information not applicable for the actual tool version they have installed.
Aspects like "Keep installations pristine" are fundamental design decisions that cannot be changed easily after.
Therefore, we do not expect pyhton or node to change in this regard to make us happy.
However, we hope that probably new tools will consider best-practices when they are created and therefore with this page we want to spread the word.
Please help us to make IT better and prevent flaws by not considering best-practices, common sense and knowledge that is already available and matured over decades.
The tool npm could have learned so much from maven (or gradle) also in other regards of their design (e.g. of node_modules) to make life and UX of developers so much better.
We got many headaches and sleepless nights while building our product over the years hitting all the anti-patterns described above that we took our time to document this.
Finally, we want to give praises and thanks to all vendors that intuitively do everything properly from the start (e.g. apache software foundation tools, etc.) and also for all developers of tools that may have some flaw or anti-pattern but take time to read this page and consider any kind of improvement.