[OpenSPIM] Getting started with SPIM plugin code

[Anthony, Neil]

Thanks Johannes, HongKee, I appreciate your time taken to get me started.

I'll check out all the links, bang my head against a few of the main starting points, and get back to the list once I get rolling.

Neil

-----Original Message-----
From: Johannes Schindelin [mailto:Johannes.Schindelin at gmx.de]
Sent: Tuesday, December 15, 2015 10:50 AM
To: Anthony, Neil
Cc: openspim at openspim.org
Subject: Re: [OpenSPIM] Getting started with SPIM plugin code

Hi Neil,

On Tue, 15 Dec 2015, Anthony, Neil wrote:

> I hope the science is treating you well.

Nah. It does not matter anymore, though, as I moved on ;-)

> I have been looking at getting started with getting into the code,
> which I see is here:
> http://jenkins.imagej.net/view/OpenSPIM/job/SPIMAcquisition/

What you found here is actually not the source code, but a so-called "Continuous Integration Server". Essentially it means that this is a web server that also watches the source code in the background and builds it whenever it gets updated.

Theoretically, it also runs all the regression tests (i.e. small snippets of code that verify that what the programmer expected to work, ahem, actually works). Practically, there is preciously little in the way of regression tests because the student who wrote most of the SPIMAcquisition code based a lot of faith in the code he wrote and skipped writing tests.

The only regression test, in fact, was written by HongKee, long after the original author moved on to other pastures.

As pointed out by HongKee, the source code can be found at

https://github.com/openspim/SPIMAcquisition

The most important thing about the source code is that it is in a source code "repository", i.e. a place where the code can not only be shared, but contributions can be integrated easily. This is possible by the use of the version control software called "Git". I encourage you to take 15 minutes to learn how to use it (and why it improves your life) at:

https://try.github.com/

More about integrating contributions below.

> I'm a semi experienced programmer (a little Java, Pascal, C, Matlab,
> Igor Pro, LabView, NIDAQ to varying levels) and I have all the
> applications in place (Netbeans, Eclipse, Visual Studio Express 2010,
> 2015, and all the java SDKs I might need).

Good. They all have support for Git (actually, VS Express does not, but VS
2015 does, I am actually working on that ;-)). So all you need to do is "clone" the repository mentioned above into your workspace.

You can then give the code a test run using the SPIMTestDrive class:

https://github.com/openspim/SPIMAcquisition/blob/master/src/test/java/SPIMTestDrive.java

> Where I get lost is how to incorporate anything I do into the existing
> code?

Yeah, unfortunately this is my mistake. I was supposed to manage the student writing the code and I failed to convince him to document things so that the next person has a chance to dive in, too. So things are pretty much undocumented.

I do not have enough time to answer questions, but I managed to give HongKee an introduction into the code base before switching jobs, so maybe you want to ask concrete questions on this list? (On this list so that the impact of the answers is maximized and HongKee won't have to repeat
himself.)

> What parts should I, can I work on?

The Open Source idea is that you work on those parts that you need to see improved. I am sure you have a couple of pet peeves that you would love to see addressed. Those are good places to start from.

And again, if you have no idea where to start "scratching your itch", just ask away, on this list.

> Do these changes need to be vetted before being incorporated?

The common process is that you create a copy of the repository on GitHub (for historical reasons, this is called "forking"). In this copy, you can do *everything* you like.

Then you will start improving the code. Once you have an improvement you think is valuable also for others, you open a so-called "Pull Request" on
GitHub:

https://help.github.com/articles/using-pull-requests/

HongKee will review the changes, possibly make suggestions how to improve or otherwise change the code, and eventually "merge" the changes.

Depending how polished you want your contribution to look, you might want to go to the full distance and follow the advice in:

https://github.com/maven-nar/nar-maven-plugin/wiki/How-to-contribute

(This is from a related project, but the advice applies to pretty much all Open Source projects.)

> How do I get started with version control?

My recommendation is https://try.github.com/, but depending how visual you work, http://eagain.net/articles/git-for-computer-scientists/ might be better. Or read the Pro Git book: http://git-scm.com/book/en/v2. There are tons of good resources available, my favorite being Git For Teams
(disclaimer: I reviewed this book before publication), but that one will keep you occupied for a couple of evenings.

> feel this is, for me, the biggest hurdle in open source coding:  Not
> being able to code, but being able to 'open source'.  I've always been
> a lone coder up until this point, so please excuse my ignorance to
> these details.

You might find it slightly challenging at first, because collaboration always requires clearer communication than "lone coding", and also the occasional compromise. I found that this requirement was most challenging to most scientists, who are basically used (even encouraged!!!) to work against each other all the time.

The advantage of Open Source coding is that you do not need to duplicate work. You put in that extra effort to make the code work not only for you, but for others, and then you can benefit from others' contributions just the same as they can benefit from yours'.

This concept is very closely related to Isaac Newton's famous words: "If I could see so far, it was only because I was standing on the shoulders of giants". It is strange how far away science has deviated from that world view.

> Also, I think maybe I'm stuck on the Maven thing.

Oh, Maven. Yep, it looks a little complex in the beginning, I agree.

Think of Maven as the system that allows programmers to stand on each others' shoulders. It allows you to define what other software components your software depends on ("dependencies"). For example, OpenSPIM depends on Micro-Manager, which in turn depends on ImageJ. And the closer you look, the more fine-grained things become. More details can be found here:

http://imagej.net/Maven

Welcome on board,
Johannes

________________________________

This e-mail message (including any attachments) is for the sole use of
the intended recipient(s) and may contain confidential and privileged
information. If the reader of this message is not the intended
recipient, you are hereby notified that any dissemination, distribution
or copying of this message (including any attachments) is strictly
prohibited.

If you have received this message in error, please contact
the sender by reply e-mail message and destroy all copies of the
original message (including attachments).