/
Solving a bug in Control Panel and uploading it to Github

Solving a bug in Control Panel and uploading it to Github

13/09/21

In this tutorial, we'll describe the process to solve a bug in the Platform's open-source version's Control Panel.

These are the steps:

  1. Build the Platform's Development Environment in your machine.
  2. Platform repo fork.
  3. Clone your Repository in the Development Environment.
  4. Initialize the platform in your PC.
  5. Solve the bug in the Control Panel.
  6. Create Pull Request in platform's Github.

1. Build the Platform's Development Environment in your machine

The platform's development environment offers you all the needed tools to develop on the platform without installing anything. It includes a Java JVM, aN Eclipse IDE, Maven, a Mongo instance as the RealTimeDB, a ConfigDB on MySQL, the git client, ...

This step is not mandatory, but it simplifies the initial configuration process. That's why we strongly recommend its use.

Development Environment for Linux and Windows are offered. We'll see next how you can install the Windows environment:

  1. Download the Windows environment for here. The environment is distributed as a ZIP file.
  2. Uncompress the ZIP in some directory (we recommend C:\OP_ENV\ or D:\OP_ENV), the password to uncompress is "sofia2".
  3. Go to the directory where the ZIP is uncompressed and run start.bat. This create virtual unit S:
  4. (If you are accessing the Internet through a proxy):
    1. Edit S:\scripts\setenv.bat and configure the proxy's values at JAVA_OPTS:
    2. Open S:\tools\maven\conf\settings.xml and edit the proxy option (server, protocolo, username, password):

After this steps you will have the Platform's Development Environment ready to work, now you need the Platform repository.

2. Platform repo fork

  1. The easiest way to fork the platform is loggin in https://github.com with your user.
  2. Once there, look for the onesait-cloud-platform repo:

 

or go directly to https://github.com/onesaitplatform/onesait-cloud-platform

3. From there, select the Fork button:

Having done this, if you browse to your profile, you'll see the repository fork:

3. Clone your Repository in the Development Environment

Once you've forked the repository to your Github user, you can clone this repo locally. To do this, use the Development Environment you installed in Step 1.

  1. If you have created unit S:, launch S:\start.bat.  Otherwise, go to the directory where you uncompressed the environment (e.g. C:\OP_ENV\) and run start.bat. This will open a command line aiming at S:
  2. To clone the repository go to S:\sources and do:

    git clone https://github.com/<your_github_name>/onesait-cloud-platform   (# Replace <your_github_name> with your GitHub profile name).

  3. Then go to onesait-cloud-platform (cd onesait-cloud-platform), and do the next command to make your upstream aims at onesaitplatform/onesait-cloud-tplatform:

    git remote add upstream https://github.com/onesaitplatform/onesait-cloud-platform.git 


  4. In this example, we want to solve an existing bug in the Platform's Control Panel on the Master branch (In a different scenario, you may be interested in working on a specific release).


4. Initialize the platform in your PC

Before you start solving the detected bug, you must initially the platform locally, that is to say, execute the base modules you are going to need and load the master data. To do this:

  1. Firstly compile the platform. To do this, from the directory where you downloaded the source code, go to the sources folder and run: mvn.cmd -Dmaven.test.skip=true clean install

  2. Once the code is compiled, launch the Platform's ConfigDB. By default, a MySQL instance included in the development environment will be used. Launch S:\scripts\ConfigDB_start.bat. 
  3. To check whether the ConfigDB started or not, launch a client with this command: S:\scripts\ConfigDB_browser.bat (with server host localhost, port 3306, username root and password changeIt!)

 

and create the onesaitplatform_config schema:


4.Afterwards, launch the RealTimeDB. In the platform's reference implementation it's MongoDB. To do this, execute the command s:\scripts\RTDB_start.bat

5.The next point is initializing the tables and the platform's repositories' master data (ConfigDB and RealTimeDB). To do this, browse in the sources folder to modules/config-init/ , then execute the config-init module with the command:

mvn spring-boot:run

If everything's OK, you can see that the tables and data have bene created in the ConfigDB:

Now you have the environment ready to work!

5. Solve the bug in the Control Panel

Once the platform is initialized, you can get on with your business of solving the bug. To do it, load the project in the Eclipse IDE that's provided with the platform.

  1. Launch Eclipse from s:\scripts\eclipse.bat
  2. The first time Eclipse opens, you must check:
    1. In File>Switch Workspace, make sure you are using workspace *S:\tools\eclipse_workspace*
    2. In Windows>Preferences>Java>Installed JRES, select *s:\tools\jdk* and select as the default option JRE.
    3. In Windows>Preferences>Maven>User Settings, select s:\tools\maven\conf\settings.xml
    4. In Windows>Preferences>General>Network Connections, check that you have configured your proxy correctly.
    5. In File>Import>Maven>Existing MavenProjects into Workspace, select Root Directory *S:\sources\onesait-platform\onesait-cloud-platform* and import all projects.


3. Now you can load the control-panel Maven project. To do it, select File>Import>Existing Maven Projects> , then select the project path (In this case s:\sources\github\onesait-cloud-platform\sources\modules\control-panel\):

4. After a while, Eclipse will have compiled the project. If you get this error:

the most easiest is to ignore this error with the next configuration:

5. Once you have compiled the project, to execute it, firstly you have to launch the databases:

  • Start ConfigDB with S:\scripts\ConfigDB_start.bat (if everything is OK, you will have an open command line with ConfigDB):
  • Start RealTime Database with S:\scripts\RTDB_start.bat (if everything is OK, you will have an open command line with RealTimeDB)
  • Start RealTime Database SQL-Service with the command S:\scripts\RTDB_HTTPServer_start.bat

Then simply go to the ControlPanelWebApplication class and select Debug As>Java Application

After a few seconds, you'll see this in the Eclipse console:

which means the module has started on port 18000.

If you go to http://localhost:18000/controlpanel/ with a browser, you'll see the application:

If you select  , you can create an user for tests, such as:

6. Now you can start solving the bug. For this example we only want to add an accent to a text missing it. To do this, go the the file i18n for Spanish language:messages_es.properties 

If you go to the line on json2ont.toolimport.title , you detect the problem, so you can add the accent to the word "importación".

7. When you've edited the file you can change the language in the ControlPanel and check that the text is correctly shown.

8. Once you've checked that the bug is solved, do a push (We recommend that a Pull Request has one single commit and push):

git fetch upstream

git add *

git commit

git push

If everything went fine, finally the push from your local repo to your gihub repository has been done:

6. Create Pull Request in platform's Github

  1. Once the bug is solved, go to the platform's github https://github.com/onesaitplatform/onesait-cloud-platform) and create a Pull Request:

2. Select then specify that you want to merge your repo's branch master to the platform's one:

As there are no conflicts, you're allowed an automatic merge.

so select


Finally the Pull Request has been created, and a Platform's GateKeeper can accept it: