Business central blog
Subscribe to blog and get news about new posts.
How to contribute to Business Central?
Business Central is partially an open-source product and anyone can contribute to the app. Today I will tell you how to do it and what is specifically available. To give an example, I will show how to contribute to the System Application.
Open source is not just about accessible code, it's much more than that. It represents a set of principles that together characterize this concept. To understand this, I suggest you read about this code of principles.
I like what Open Source Initiative suggest as good definition of open source:
https://opensource.org/definition-annotated
I like what Open Source Initiative suggest as good definition of open source:
https://opensource.org/definition-annotated
In order to answer this question, you need to remember that Business Central actually includes many modules because of this it is not possible to give a definite answer. Therefore, I would emphasize the main components and the possibility to contribute to them. So if we can't contribute it's no longer open source for us.
Of course, my classification is quite conditional, but it will still gives you the opportunity to understand the main idea. In fact, only the BC Platform and the AL compiler remain a black box for us. We can neither propose changes to it nor even see what's inside.
The platform essentially acts as a glue that binds everything together. For example, when I was just starting my journey as a developer, I received an interesting task in Navision 2017: to change the size of the standard "Ok" button on a card page. Of course, all serious developers refused such a task as it seemed rather silly. But as a beginner, I found it interesting, so I began analyzing and understood that the Navision platform was responsible for UI rendering and that to change anything, one needed to at least somewhat understand the platform's logic.
I managed to find out that certain .dll libraries of the platform were responsible for this, and that the "Ok" button always had the same GUID identifier. Therefore, I wrote a small library in C# that accessed the "Ok" button and changed its size and styles. This library was simply registered as an Add-in.
This is just one example of what the platform is responsible for. Of course, in Business Central Cloud, we are deprived of such possibilities(we can build our own UI via JS add-in), and that's good! I shudder to remember some of the Navision Classic forms I had to deal with. Believe me, standardization is very beneficial.
Before we begin, I would like to draw your attention to the fact that every repository has its own rules, and before creating and proposing anything, you are obliged to familiarize yourself very carefully with them. Otherwise, there is a risk that your help will only result in problems and a waste of time. Respect yourself and the efforts of others.
Furthermore, if we're talking about contributing code, I am convinced that every change should be accompanied by test coverage in test codeunits. For example, for System Application, there is a rule - new methods in public interfaces must be accompanied by test coverage, for instance, for Sharepoint/AzureBlobClient, and so on. However, I still believe that this should be done for any change in the code for such a large product as Business Central.
To summarize:
- Read the rules carefully.
- Cover your Pull Requests with tests.
- Don't make any breaking changes with Pull Requests, use obsolete method instead
Since I have already contributed to the System Application, I will talk about that. Unfortunately, there aren't any good instructions on how to manage the dev environment and how to test. Therefore, I will share what I have figured out on my own, and I'm not sure if my approach is the most optimal. You're always welcome to correct me.
So, the System Application is located in the BCApps repository, and the first thing we need to do is carefully familiarize ourselves with the rules that apply to this repository.
So, the System Application is located in the BCApps repository, and the first thing we need to do is carefully familiarize ourselves with the rules that apply to this repository.
So, we've read the rules and want to fix a problem or implement a BC Idea. For this, we need to create a GitHub Issue in the repository and provide all the necessary information, and before starting work, wait for your Issue to be Approved.
This is an example of an Issue I created for Azure Blob Client, which essentially fixes the non-working PutBlockList() method by adding an intermediate PutBlock() method and the missing BlobName parameter.
After we have received the "Approved" label, we can directly start working. To do this, we need to fork our own copy of the BCApps repository. This can be done in different ways, but for clarity, I will show you how it's done using the web browser UI.
Essentially, this creates a copy of the repository at the time of executing this method. This, in turn, means that your fork might be behind the current version. Therefore, it's important to keep track of your fork version and synchronize it as necessary. For this, you can also use the web browser UI or through the terminal.
Now, we can download the repository locally, either through commands or through the UI in VS Code via git clone action.
Next, we simply create our own branch from origin/main that will be used to work on our Issue.
Now for the most interesting part, we need to create a development environment in Docker and compile the System App by installing it on your Docker container. I assume you've already installed Docker and it's ready for use. The project already includes al-go scripts that you can use for compilation and creating a Docker container. Initially, I used a script that recreates the Docker container each time, compiles a specific project from the projects folder. However, I didn't find this too convenient because we can specify only one particular project, and the execution time is quite long. Nevertheless, here is the command you can invoke in the VS Code terminal.
.\build.ps1 -ALGoProject "System Application"
As a result, we will get an empty container with only the one extension we specified earlier, which, honestly, is not very convenient.
I prefer the option to directly call NewDevEnv.ps1, where we can specify the path to the extensions we want to compile and install with an asterisk, for example, '.\src\System Application\*'. Also, if a Docker container with that name already exists, it won't be recreated from scratch; instead, it will only reinstall the extensions specified in the path. The only thing you need to do is manually delete the compiled files from the .artifactsCache folder so that this command compiles them anew. Overall, this method is faster than the previous one.
.\build\scripts\DevEnv\NewDevEnv.ps1 -containerName 'BC25systemapp' -userName admin -password 'Qwerty123!' -projectPaths '.\src\System Application\*'
As a result, we will get an environment with several extensions right away, which is already better than last time.
But it's still unclear how to test and work if there's neither the Base Application nor at least a Test Runner to run your tests. For this, I simply go to the .artifactsCache\symbols folder, take the app file I need from there, and install it using bccontainerhelper.
Here is an example of how to install the AL Test Runner to run your tests for the System Application.
Publish-BcContainerApp -containerName bc25systemappnew -appFile "C:\Users\Drakonian\Documents\AL\BCApps\.artifactsCache\symbols\Microsoft_Test Runner.app" -sync -install
I think you've grasped the main idea. But in reality, it took me quite some time to figure this out. I believe Microsoft could still improve a lot in this area and make the instructions clearer and the scripts more convenient. In any case, this will happen sooner or later.
After ensuring that the code works as intended and we are ready to submit it, we simply need to create a Pull Request from your new branch to the main branch of BCApps. This is an example of my PR for the Azure Blob Client.
After ensuring that the code works as intended and we are ready to submit it, we simply need to create a Pull Request from your new branch to the main branch of BCApps. This is an example of my PR for the Azure Blob Client.
After you have created a Pull Request and have been assigned an internal task id, GitHub CI/Actions will be triggered with all checks and tests, which will take some time. If you see that the CI has errors, you can immediately fix them without waiting for a code review. Anyone who wishes or a Microsoft employee will conduct the code review.
While I was writing this post, Alexander Holstrup from Microsoft had already started working on improving the dev experience with containers. I will definitely update my post after the work on this PR is completed.
March 29, 2024
Author: Volodymyr Dvernytskyi