Working on JISA

If you find yourself in a position where you need to change something in JISA, for instance you may want to add a new instrument driver or fix a bug, then this page will show you how best to go about getting set up to do so.

Prerequisites

Before we start, you should make sure you have all of the following:

1. A GitHub account
2. Access to push to the JISA repository using your GitHub account (drop me a line at [email protected])
3. IntelliJ IDEA installed on your computer: https://www.jetbrains.com/idea/download
4. Git installed on your computer: https://git-scm.com/install

Cloning the JISA repository

Start up IntelliJ IDEA. You will now want to create a new project by cloning JISA from GitHub.

If you are on the welcome screen you will want to click a button that says something like "Clone Repository", like in the screenshots below

Otherwise, you will want to click the "hamburger"/three lines button in the top-left, then go to "File" > "New" > "Project from Version Control..." like in the screenshot below

Either way, you should get the same window pop up. In it, select "GitHub" on the left. If you're not logged in already, press log in via GitHub button and login. Then select OE-FET/JISA in the listof repositories, then click "Clone"

Wait for that to complete. When it's done the project should open. If you are asked whether you trust the project or not, make sure you say you trust it (as in the screenshot below).

Upon the first time opening it, IDEA will analyse and index everything. If things are missing (for instance, there's no Java SDK installed), it will tell you in a banner at the top of the code editor. In such a case, just do what it automatically suggests. For instance, if you have no appropriate Java SDK installed (that it can find), just let it download its own to use.

If all went well, you should have a window that looks something like this:

Creating a working branch

Next, before you start going and changing stuff, you should create your own branch. This way, your changes shouldn't conflict with any other development that might be going on at the same time. When your done implementing your changes, you can request for your branch to be merged back into the main working branch so all have access to your improvements.

By default you will be on the "master" branch to start with. To change this, click on where it says the current branch in the top left (i.e., it should say "master"). Then go down to the "master" branch listed under "local", click the arrow next to it, and select "New Branch from 'master'..." like so

Alternatively, you can create a branch off any other branch in the repository instead. For instance, currently, a lot of work is being done on the "devices_revamp" branch (and this is the branch that FetCh is currently based on, for instance). To do this, go to that branch instead, which will be listed under "Remote"

Either way, give your new branch a name that indicates the feature you are adding or bug you are fixing etc. You should now be good to go.

Editing source code

The source code for jisa can be found within the "src" directory within the project. Therefore, if we wanted, for instance, to edit the K2450 driver, we would navigate to "src" > "jisa" > "devices" > "smu" > "K2450". However, it is much easier to search for classes by name. To do this press crtl+n on your keyboard, then type in the class name.

However, if you intend to create a new class, then you will need to navigate to the directory (or "package") where it should be created, right-click on it, then select "New" > "Java Class". For instance, if wanted to add a new driver for an SMU or SPA, I would navigate to "src/jisa/devices/smu", right click on it, then create a new java class like so.

Building JISA.jar

The project in IDEA is configured to automatically build a new JAR file any time the project is compiled. To do a full recompile, click the menu button ("hamburger"/three lines) in the top-left, go to "Build" > "Rebuild Project".

Assuming there were no errors, when this finishes you will have a new JISA.jar file in the root directory of the project.

Commiting and pushing your changes back to GitHub

When you're done and want to share your changes back to GitHub you will want to "commit" your changes then "push" then to GitHub. The easiest way to do this is to click the "line with a circle in it" button on the left-hand sidebar, enter a message for your commit describing what you've changed, then hit "Commit and Push..."

You might have to ignore your way through some warnings. If it asks for you to set your identity, enter your name and the same e-mail address you used to sign up to GitHub with.

Merging your changes

If you want your changes to be merged into mainline JISA, then you will need to open a "Pull Request" on GitHub. Easiest is just to ask me to do this.