Lowering barriers for new contributors

[PaulWessel]

Potential contributors to GMT who might help with coding, documentation, testing or other aspects of GMT maintenance and development face initial hurdles to get up and running. These are hardware and software related, mostly. While the Wiki explains all the prerequisites that need to be met, it can be a bit daunting for newbie developers to get going. What can we do to lower the barriers? Here are some thoughts; feel free to add to them.

1. In GMT 4 days we had a newgmtguru shell script that new developers could use (or old developers) for setting things up on a new computer - I basically wrote it for myself for that reason. It would take care of all the drudgery of installing prerequisites, checkout GMT, coastlines and other required data. While that script (if I could find it) would no longer be relevant, it is true that it would save time and frustration if we had, say, a series of very similar scripts (or one with lots of checks for OS and distros) that could do all of this. E.g., for me on my Mac using MacPorts I could quickly get set up on a new laptop by running the hypothetical script gmt_devel_setup_macports.sh. it could ask some basic questions with reasonable defaults (like directory selections) and go to task.
2. Another similar method would be to create a package called gmt-devel which would install all the prerequisites and tools that are required to develop GMT (which is a bit different from what is required to install GMT as a user). This package would not install GMT since we want to get the source form the git repository, but it would lay the groundwork. One would need to maintain separate packages for various Mac and Linux distributions (similar to any newgmtguru script). Of course, one of the things that might get install could be the helper script discussed in (1).
3. Create a Docker image that would allow all this to happen. I know so little about this and can barely spell Docker, so we need knowledgable folks to expand on this. My understanding is that we currently do not have the skills to pull this off ourselves. Perhaps @leouieda, @seisman and @meghanrjones have thoughts on this option.
4. Set up developer environments on a cloud server. This would lower the hardware requirements for new developers, but would push the cost to the project. Given the plan to live sustainably (i.e., not a lot or any NSF funding) we should strive towards a no-cost solution that will not be disrupted. It is easy to try out an initially free solution only to learn down the road that the free solution is coming to and end and here are your options for payment. That is disruptive.
5. I am not sure about the Windows side but @joa-quim can address concerns there. We do want it to be possible for anyone to quickly get up and running to develop on Windows as well since we have fewer such volunteers - no doubt due to the less-clear path for success.

A parallel thread is the old mantra that the documentation on how to do things can always be improved. It has gotten a lot better thanks to @meghanrjones, but it can still be improved, especially if we put on our rookie glasses and try to follow instructions. We all tend to make assumptions about what is well known and those often fail for others with different backgrounds.

[anbj]

This reminds me of the good old GMT days where you filled out the web form and got a script in return that installed gmt.

I've never built gmt on Windows. I would very much like to be able to though. I've tried (without success) building other software on Windows (but not many), but it gave me an afterthought of "that was a whole lot of work, for no results at all".

For me, building GMT from source is surprisingly easy.
Before I discovered WSL (around 2017) I never built from source, because I was trapped in Windows (ref. the disclaimer).

After that, using Linux, it became very simple and enjoyable.

When I setup a new system, I run an init script, which basically contains the following:

sudo apt install -y build-essential curl git cmake libcurl4-gnutls-dev libnetcdf-dev gdal-bin libgdal-dev libfftw3-dev libpcre3-dev liblapack-dev libblas-dev libglib2.0-dev ghostscript graphicsmagick ffmpeg

mkdir -p ~/gmt/gmt
mkdir -p ~/gmt/b
mkdir -p ~/gmt/share/coast
mkdir -p ~/gmt/share/dcw

git clone https://github.com/GenericMappingTools/gmt ~/gmt/gmt

curl -L -o ~/gmt/share/coast/gshhg-gmt-2.3.7.tar.gz "https://github.com/GenericMappingTools/gshhg-gmt/releases/download/2.3.7/gshhg-gmt-2.3.7.tar.gz"
tar zxvf ~/gmt/share/coast/gshhg-gmt-2.3.7.tar.gz
mv gshhg-gmt-*/* ~/gmt/share/coast
rm -rf gshhg-gmt*

curl -L -o ~/gmt/share/dcw/dcw-gmt-2.1.0.tar.gz "https://github.com/GenericMappingTools/dcw-gmt/releases/download/2.1.0/dcw-gmt-2.1.0.tar.gz"
tar zxvf ~/gmt/share/dcw/dcw-gmt-2.1.0.tar.gz
mv dcw-gmt-*/* ~/gmt/share/dcw
rm -rf dcw-gmt*

cd ~/gmt/b \
&& cmake ~/gmt/gmt \
-DCOPY_GSHHG=TRUE \
-DCOPY_DCW=TRUE \
-DGSHHG_ROOT=~/gmt/share/coast \
-DDCW_ROOT=~/gmt/share/dcw \
-DGMT_OPENMP=ON \
&& cmake --build . --parallel $(getconf _NPROCESSORS_ONLN) \
&& sudo cmake --build . --target install

I guess there is a point where trying to simplify things actually makes it more complex; e.g. creating black box scripts that does the stuff for you.

Forcing newbies to edit ConfigUser.cmake I think quickly leads to confusion, so it's better to define them on the command line. Then they can dig into it later if they want.

It's also important that the user feels that he/she succeeded. Building gmt which works is highly motivational and encourages learning more.

[joa-quim]

"that was a whole lot of work, for no results at all".

Had you to debug on Linux and I would love to see you maintain the above.

Regarding building on Windows. I prepare the paste but it's ignored.

#4718

[anbj]

I’m ignorant and have never debugged. So you’re eligible to slap me with a heavy manual.

And actually, I think I did try to compile gmt on Windows once. And it failed.

[joa-quim]

And about the lowering the barriers. All fine if those barriers are ours too (barriers or just annoying) but I don't worry much in what regards new contributors. If they are really able to contribute the present barriers should be a nothing for them too. If they are not able to overcome them I don't expect they can really be able to contribute with bug fixes or new code.

[joa-quim]

with a heavy manual

Not really much for the manual. Only thing that needs explaining is on how to start a project for debugging, next is just to use the Visual Studio debugger, which is a fantastic tool.

[anbj]

I’ve heard ‘The C programming language’ by Kernighan and Ritchie gives a good punch.

[PaulWessel]

I do think it is possible to have skills as a programmer and yet find it too overwhelming to set up the workspace to get to the debugging part. Each time I start on a new machine I reinvent lots of wheels and spin them in the mud for a while until I remember some special thing I had to do last time (a year ago or more). So I definitely hope this benefits us as well.

[anbj]

Reducing friction is always a good thing.

Unless you’re on a road of course.

[joa-quim]

yet find it too overwhelming to set up the workspace to get to the debugging part

OSX 😄

[PaulWessel]

Well, you just heard that @anbj got stuck trying on Windows.

[brioglade]

ALL guys. You are so great. You always think about the project and benefit more people. I admire and envy what you have done.

[joa-quim]

Hmm, I say a reference to "it failed" but no idea what. And, Andreas will surely forgive me, but I was referring to people who know programing, namely at least a bit more of the basics of C. But ofc, Xcode can defeat anyone.

[Esteban82]

What can we do to lower the barriers?

I think that the first thing that we should do is to make a video tutorial on how to do it. I have little programming skills and all the explanaitions soon became difficult to follow. In fact, I manage to build GMT on Linux after I saw the belowe video despite being in Indonesian (I think).

https://www.youtube.com/watch?v=Ogfkzaqjmrk

And I think I could start running the tests and debugging with similar videos.