[OpenSPIM] Getting started with SPIM plugin code

[Johannes Schindelin]

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