Set up

The goal is to make a command line interface tool for Pagure. I named it cranc, since Pagure is a hermit crab. Cranc is crab in catalan, the language spoken in Catalonia which I’m learning now.

The project is hosted on Pagure.io. Firstly it was necessary to create a cranc virtual environment. Then my mentor helped me to make a setup file, requirements.txt and the cranc application cranc.py with __init__.py file. My first commit was ready!

Having the initial setting ready I could make first group with first command in Click. For the moment the only functionality of cranc is to list all pull requests of a project.

Inspiration

The idea is to learn from the best. A lot of inspiration comes from popular command line tools such as git review (cli for Gerrit) and kubectl (cli for Kubernetes).

Cranc is being built on libpagure library and takes after of previously written Pagure cli tools, such as argparse based cli and click based pag. The main difference from this two is that cranc is using both click and libpagure.

My mentor suggested that we use a consistent structure of commands. In cranc case all the commands will be command <action> <resource>, where the action is a verb and resource is a noun. I took the libpagure library a turned the functions into commands.

And now to the struggles part

Before creating even the simplest project layout, I needed to read a lot of documentation and see several examples of how setup.py files actually look like, what belongs to the requirements.txt and what is actually python3 built-in and how to make a .gitignore file. My mentor was helping me and showed me guides and examples from her own code.

Basically every line of code I rewrite several times and still that doesn’t prevent me from… emmm…for example making a pull request with my private API key, which was hanging there publicly for several days..Also, I find myself incredibly slow in reading and understanding documentation, especially when it’s written too professionally. I usually prefer to read blogposts with examples, stackoverflow or nicely written guides.

Anyways, I finally made my first thing work: cranc is now listing pull requests!

Time to create the first test

My mentor suggested to use pytest library (I was struggling half day trying to figure out how Mock should work, but I’ll get there later :) ).

The libpagure library has already built-in filters for status, assignee and author. For the moment cranc/libpagure is filtering well the open and merged pull requests. However, I ran into a problem. While filtering the closed pull requests, I got both closed and merged. For that I needed to go to the pagure code and I found piece of code which probably caused this and I made it behave the way I wanted.

But how to test it before I send a pull request to Pagure?

And here another struggle comes. My idea was to run a docker instance and modify the script for populating the database with some more pull requests, so I had something to try the filters on.

While trying to add some fake data into local database I faced several problems. After investigating for some time I discovered one small mistake/typo and one import not behaving well.

The issue I found was a non existing flag status label, which was throwing a KeyError when run in the development pagure instance. Pull requests can be labeled with 5 different statuses. The constant FLAG_STATUSES_LABELS allows to label a pull request with these 5 kinds of flags: “success”, “error”, “failure”, “pending” and “cancelled”. However, in the code the constant had a value status="Open", and that ended up in crash. I just changed it to status="success" and the error was gone.

The second issue was an import error. Actually there were two. One module was not imported at all in one file, and a full path to a module was missing in another file.

I fixed it and could finally test my change - and it worked!

If I get the pull request merged on Pagure, cranc will be hopefully filtering the pull requests by status as I want it. Or I will face more challenges :)

What helped me

I saw some advices from current or former Outreachy interns and I benefited greatly from that. Maybe it will be of use to somebody if I mention my little tips for making my life better. Here they are:

[x] Writing notes. Into some personal README. This prevents me from asking over and over the same questions or google for 20th time how to do git stash pop. (True story, I had to make an alias in my git config, so now I call git unstash. Sadly, writing it there finally made me remember it.)

Try not to have several READMEs in different directories like me.

[x] Asking questions. To the mentor, to other contributors/authors, to people I know from coding groups, to anyone who knows some programming. And also explain. I sometimes come up with an idea when I’m describing my problem to my mother or granny :)

[x] Keeping excited. Use the excitement of starting a new project as much as you can. I’m an Outreachy intern for nearly a month now and I’m still climbing up on the excitement hill :) It doubles all the little successes and increases significantly the frustration tolerance. Oh, and it also makes me want to continue working on weekends, holidays and for example write this part of the blogpost on christmas eve when the kids are sleeping, instead of watching a new episode of my favorite series.