How to contribute to an open-source Oracle APEX Plug-in

I am a huge fan of free open-source software (FOSS). It is basically the backbone of the modern digital world, as pieces of software like Linux, SQLite and many more are so omnipresent.

Next to free use, FOSS also has the advantage that it allows anyone to learn from the code of other developers. I am always amazed at how decentralized version control systems like Git make it super easy for anyone to contribute to a project. I think it is quite wholesome when strangers from different parts of the globe come together to build something remarkable.

In my opinion, the Oracle APEX community has some outstanding open-source projects, but the spirit is not as big as in other programming languages. One of the complications is that when it comes to APEX, we deal with hugely generated SQL files, where it is not as easy to work together as in other high-code programming languages. You are better off changing an APEX app from within the same workspace, then branching into different environments and trying to merge the changes later. It is also difficult to generalize problems in such a way that others can benefit from your specific implementation.

Here is a list of some of my favorite open-source APEX/Oracle projects:

I am probably missing lots of stuff here. There are, especially, many more PL/SQL and SQL script repositories out there on GitHub that provide so much value.

In this post, I want to focus on how to contribute to an open-source project. As an example, I am contributing to a Template Component plug-in, but I am focusing on the general steps you have to perform on GitHub and not on the specific plug-in changes. So you can apply the same steps to any other open-source project. I will contribute to Timo’s Responsive Number Counting Template Component Plug-In.

You can always go through the issues section of any open-source project and see if there are any tasks you can help with.

If you already know what functionality you want to extend, you should remember that communication is key. It is advisable to contact the plug-in author before doing anything. Tell them about your idea and ask if they are interested in your contribution. If they are not interested, you can still fork the repository and create your own version. But if they are interested, you can work together and maybe even get some guidance from the author.

Also, don’t be afraid that your contribution is not good enough or too small. Even improving help texts or fixing some small CSS issues is super helpful. And if the author, e.g., has different code standards, he might tell you in his code review. You can then just adjust your code and still get your contribution merged. In the end, everybody wins as the project improves.

Before we can start developing, we need to set up a clone of the source code. For public GitHub repositories, you can create a fork. It will be under your GitHub account, with the same name as the original repository. So out of alice/apex-plugin you will get a copy named {username}/apex-plugin.

Clone that forked repository to your local machine, and you are ready to craft some changes. You can just commit and push your changes. When we are done, we will ask the author to merge our changes back into the original repository.

Instead of directly changing the SQL files, we want to work on the plug-in in an APEX instance. This part already requires more thought than is obvious. One problem with plug-ins is the absence of downward compatibility. This means that if you develop a plug-in in a 23.1 environment, you cannot import it into an earlier APEX version like 22.2.

Some developers want to make plug-ins accessible to a wide range of users. In this case, the way is to develop them in outdated APEX versions. That’s why we first aim to check the APEX version of the plug-in we intend to contribute to. We can do that by looking into the plug-in definition .sql file. In Timo’s case, he has it in the Git repo at /plug-in/template_component_plugin_apex_therwix_responsive_number_counting.sql. In line 22, we can see in which APEX version the plug-in was created:

As this is the newest version, I just imported it to my apex.oracle.com workspace.

If this is not the case, there are two options. The first would be to set up or find an instance with the same version as the plug-in. On the other hand, you could contact the plug-in author. Maybe they can provide you access to a workspace, or they might agree to only support the newest version for the next update of the plug-in.

In my case, I added some attributes and changed some JavaScript code in the plug-in. I also increased the version number in the plug-in.

Timo stores the plug-in definition file as well as the JavaScript and CSS sources in the Git repo to make it easy to track changes. So I went ahead and exported the plug-in from my APEX instance and replaced the files in the Git repo with the new ones. I also pasted the modified JavaScript file. Now we can just commit the changes and push them to our forked repository.

If you are interested in the changes I made, you can check out the commit.

Now we can ask the plug-in author to merge our changes back into the original repository. This is done by navigating to your forked repository on GitHub. If you have made any commits, you should see the contribute button.

After clicking on it, you get to a page where you can double-check your changes. If this looks good, you can click on the “Create pull request” button.

Now you can add a title and a description to your pull request. Try to make it as easy as possible for the author to understand what you did and why you did it. I added screenshots and explained all the changes.

Now we can wait for the author to review our changes. This can, of course, take time, as most open-source projects are worked on in the spare time of the developers.

If the author does a code review and asks you to change some things, you can apply the requests and push the changes to your forked repository. The pull request will then automatically be updated. If the author is happy with your changes, they will merge them into the original repository. Congratulations! You have successfully contributed to an open-source project! GitHub will also now list you as a contributor to the project.

If the author rejects your changes, you can continue working on your fork. The same goes when the author does not respond at all. You can share the fork with others, and maybe people will love your changes and use your fork instead of the original plug-in.

Life is always about giving and taking. The more people contribute to open-source projects, the more we all benefit. This results in APEX becoming a better platform, which we all benefit from. I hope this post helps and motivates you to get started contributing to open-source projects.