Introduction

I get a lot of people who say they want to start contributing to Julia. I link to our spot on Up For Grabs and Iain Dunning’s great Contribute To Julia repo. But we don’t see a lot of new people opening PRs. I started out a year ago, opening my first PR, and I was so scared. I had no idea what I was doing! Now, I have more than 200 commits to Julia master. I decided to make a detailed pictures-and-text guide of how I:

I use OSX day to day, and all of this should work on Linux too. The steps to get going on Windows are a little more involved but once you have a working Julia build, you are good to go.

Getting Started - Cloning and Building Julia

The first thing you will need is a local clone of the Julia repo. The Julia repo is hosted on Github, and README.md has instructions on how to get started. You can follow along there, or, in most cases (I call my “work” directory Projects),

cd ~/Projects
git clone https://github.com/JuliaLang/julia.git
cd julia
make -j 8

I use https because I have 2FA on and I use personal access tokens. SSH is fine too. Since I’m on a fancypants iMac, I make with 8 threads (-j 8 tells make how many cores it can use for the build). If this is your first time building julia, now would be a great time to get a coffee. The initial build takes a while.

If you’re reading this, you probably don’t have commit access to Julia. That’s fine - we can follow the Github help article on forking. Make sure to add your fork as a remote for your git repo. What I did:

git remote add kshyatt https://github.com/kshyatt/julia.git

I call my own personal forks of things kshyatt and the organizational copy origin, but any name you can remember works.

Make Sure We’re Up To Date

During the interim between cloning and building, new commits might have made it into Julia master. We need to make sure we’re up to date. I do this using:

git checkout master
git fetch
git status
git pull origin master

This gets our master branch up to date with the remote one from origin (in my case from the JuliaLang repo).

Find Something To Work On

Let’s head on over to Julia’s issues page, which has many issues that take a lot of expert attention. Not all do, though. Usually, problems/feature requests/bugs that are appropriate for new contributors to tackle are filed under the intro-issue label. You can get to it by clicking on the labels header like so:

labels introissue

I’ll pick my own issue, which is about missing features in our linear algebra library. Here’s a screencap of it:

myissue

I picked the first item to work on - full doesn’t work for Symmetric{SparseMatrixCSC} types! The first thing to do is to make sure this is still a problem, since the issue is kind of old.

Reproducing The Failure

Going back to the terminal, I make a test symmetric sparse matrix and attempt to call full on it.

a = sprand(5,5,0.2) #make a 5x5 sparse matrix with random elements
a = Symmetric(a + a.') #make it symmetric
full(a)

and what did I see, but:

reproduce

So I’ve reproduced the failure.

Finding The Problem

The error I got suggests that the problem is with something called copytri!. Symmetric is a tag we put around another matrix type. It’s defined in base/linalg/symmetric.jl. Below, I’ve opened the file up in vim (or you can go look at the old blob on GitHub):

What the error above tells us is that Julia has no copytri! method that takes a SparseMatrixCSC as an argument. We can see all copytri! methods using the aptly-named methods function:

methods

copytri! is not exported from the Base.LinAlg module. There are two methods, and just like the error says, neither method takes SparseMatrixCSC. So we need to:

Adding the method

It looks like the current copytri! methods all live in base/linalg/matmul.jl. The matrix multiplication methods for sparse matrices all live in base/sparse/linalg.jl, so let’s put our function there.

I opened the sparse file as a pane next to the dense one since we can probably build our new method with some slight modifications to the dense one. This might not have optimal performance, but it’s enough to get started.

copy

First, we need to modify the argument list. Our copytri! will take SparseMatrixCSCs as its first argument. We can leave the others untouched for now.

fixargs

copytri! is supposed to copy one triangle of A into the other (since the lower/upper triangles of a symmetric/Hermitian matrix are {c}transposes of each other). The most naive thing we can do is just add the matrix A and its transpose.

Writing a test

The tests for this file are in test/sparsedir/sparse.jl. The top of the file is a pretty reasonable place to put this test. Let’s start off with:

And running it shows:

firsttest

Welp. Something went wrong here!