Running reviews on Open Exchange

Article

Robert Cemper · Jun 12, 2021 2m read

For several weeks I'm creating reviews on OEX.
So I'd like to explain to you the criteria that I apply to find my ratings.
Of course, each reviewer is an independent person and has his own criteria and his own opinion.
And that's good and important! As Winston Churchill once said:

"If 2 people always have the same opinion, then 1 of them is superfluous"

There are packages that I skip and don't review

- Pure product announcements
- Packages where requirements exceed my resources and capacities 
 (e.g. external SMS service, distributed HW, cloud-based installations, .. )
- Packages on private repositories that can't be downloaded.
- Packages where I just don't understand what the subject to achieve is

I check Description in OEX and/or README.md on GitHub

- Is there an explanation of the goal that I understand 
- Is there a description of how to install the package 
- Is there a description of how to test/verify the package
All these points can be covered explicitly or by a link to
an article in Developer Community. Only Empty is not accepted.

Is a Docker container prepared?

For a single class the cleanup after testing might be easy and acceptable
But if a more complex setup is required (e.g. Interoperability, Node.js, ....)
only a container multiple containers can guaranty to deinstall 
all components and keep your testing environment clean
- "docker-compose build"  is the first check and often the first disappointment 
- "docker-compose up -d"  is the next test
- "docker-compose logs" often detects startup issues.
If I can identify the problem and find an acceptable workaround 
I will fork the repo, fix it and place a PullRequest.

If there is no Dockerfile nor docker-compose visible

I use an appropriate template, install and start it. 
Then I try importing the package
This often works also for packages that are not explicitly dedicated to IRIS.
As mentioned earlier, clean-up is simple: 
Remove docker image, remove cloned repo. BINGO!

Now I try to exercise the examples or demos

Existence of a UnitTest clearly raises the rating
- are demo/test data sets available and a guide on how to make use of it
- is there eventually also a video that shows the expected behavior
A hint for videos: 
Please speak slowly and simple and as precise as possible and make clear breaks
Most consumers are non-native speakers and may struggle with complicated 
lingual constructs. The focus is on technology not on language excellence.

Take the packages from ISC Training as examples of professional setup

I tried also packages for the Health* products, even as speaking "medical" 
is not so much my world. But I was surprised to learn and refresh a lot of features 
around the base technology: 
Interoperability and its operation and management and troubleshooting.

Nigel Salm · Jun 12, 2021

Hi Robert

This is an ambitious project with a wide scope of scenarios to take into account. I have spent quite a lot of time recently looking through OEX to find applications that might contain code or functionality that would help me understand how to use features of IRIS or external technologies such as Bootstrap, Angular, Python. This took me into a world of Node.js, NPM, Gradle, Gulp, GIT, TypeScript, Packages which I have either had little or no knowledge of as they have never been required in the applications that I have built over the last 30 years. To be quite honest I have relied on the Readme.MD files in the OEX install kits to install many of the applications that looked promising. I follow the instructions and generally speaking 90% of the 50 applications that I downloaded did install easily and though I didn't necessarily always run the application (as I was more interested in the application code) but those that I did run worked as expected.

Some of the OEX Readme.MD documents are very good with detailed installation notes (especially those that take into consideration that not everyone is using UNIX or Docker or Containers or ZPM so I appreciate it when they include installation notes for each of these scenarios). Information on any prerequisite requirements is especially appreciated when they involve 3rd party apps or utilities that may not be familiar to those of us who have lived in a Cache/Ensemble/IRIS cocoon for many year. Step-by-step installation guides and how to activate the application once it is installed are very important especially when the application makes use of 3rd party technologies.

Of the 50 apps I downloaded there were very few examples where the Readme.MD file contained only the barest of information but none were so limited that I was unable to install or use the code. When the Readme.MD file is expansive I have developed a habit of copying the contents into a word document and filing them for future reference as well as adding them into the company knowledge base for other developers to review. One area of documentation that tends to be overlooked iare notes on how to uninstall the application. Applications that have been installed using NPM Install can be uninstalled with NPM Uninstall. Many of the apps that I have downloaded recently were built using ZPM and as we don't yet use IRIS at the company I work for any exploration of IRIS has had to be in my own time and so I started using ZPM and have used it to download quite a few repos. I was very impressed. There have been 2 or 3 installs that threw up errors as they required an earlier version of npm or some other 3rd party component than the version installed by other applications and generated either medium or fatal errors. Some of them can be fixed by using npm audit fix or npm audit fix -force.

One of the applications I installed "Forms" installed entire libraries of bootstrap/MDB/Font-awesome kits of .js/.css/fonts/images/icons and I am not sure how easy it would be to uninstall it cleanly. In an extreme example such as this then I think that there should be comprehensive notes on how to uninstall the application and remove any residual files and directories that remain after the uninstall. So I think that your rating algorithm should factor in the quality of the uninstall instructions based on the complexity of the installation.

I would be very willing to assist you in this exercise if there is anything that I could contribute.

I also think that as DC members we should be more proactive in writing reviews of applications we have downloaded and comment on our experience of installing and using the application, how our knowledge of the technologies used has been benefitted, and maybe some notes on why other DC members should consider downloading the app if it is a really good example of an IRIS component usage especially if they have been able to leverage that knowledge in the development work they do in their day jobs.

One final comment I'd like to make is that the Coding Competitions have been an excellent way of getting developers to explore aspects of IRIS and IRIS for Health that they are probably not being exposed to in their day jobs and has resulted in some truly useful applications especially in the areas of VS Code extensions, ML, AI, Python, Angular, Node.js, Git which are used by so many developers who do not use InterSystems products and as InterSystems are investing a lot of energy in integrating these technologies into IRIS which goes a long way to encourage developers who don't currently use InterSystems products to start seeing IRIS as an interesting technology to investigate especially if they can adopt IRIS into their current development toolset supported by a vibrant Developer Community, well documented, and an ever-increasing repository of sample applications that use technologies such as Node.js, Python, Angular, JSON, OAuth which are all high on the list of most popular languages and security solutions.

Nigel

2 0

Evgeny Shvarov · Jun 12, 2021

Thanks, Robert!

The clear Readme.md - is the must!

I agree on docker, ZPM, testing - these 3 is a kind of respect to other developers: easy to install, easy to clean up.

And if it is ObjectScript the code-quality with no bugs and warnings also ups the rating.

BTW, I think it makes sense to add a CONTRIBUTION.md to the templates - to describe the way and terms of the contribution to the projects.

1 0

Olga Zavrazhnova · Jun 15, 2021

Thank you Robert! It's crucial to have reviews on Open Exchange. We so appreciate your great job on this!

We invite all the developers to leave reviews for applications on Open Exchange and be rewarded on Global Masters:

In this challenge you can get 500 points for each review on Open Exchange

In this challenge you can get 500 points for each submitted Pull Request

2 0