A few weeks ago I've open sourced issues-helper. It allows you to easily interact with issues on GitHub and GitLab, from the command line.

gli o --assignee clementd --label improvement "Degauss the frobulator fluxfield"

Let's see why and how it's done.

TL;DR

Issues are a good way to keep track of decisions in a project. Opening issues should be easy so people don't forget to write down why they've done things. Opening issues from the command line with minimal fuss is a good thing:

gli init # generate initial configuration
gli o "Issue title" "Optional issue text"
  # add --open to open the issue in the browser once created
  # add --assignee to assign issue
  # add --label to add labels to the issue
gli l # list issues
gli b # open the project homepage in your browser

Issues. Use them.

At Clever Cloud, we use git (and GitLab) a lot. In addition to just using git for code, we also rely a lot on issues. Many discussions end with "please open an issue and sum up what we've just said".

Issues are not just for bugs, we use it as a way to track decisions. Some projects don't even have code and are just there to track discussions and decisions.

My goal, as a CTO, is to make sure we keep track of all of our decisions. So I need people to open issues, to open them often, and to open them early.

Processes. Make 'em easy.

I work with people, not with robots. While I trust them and I know they're good at what they do, I just can't expect them not to make mistakes, or in that case follow processes with no clear incentive. So I needed to remove friction when opening issues. When we interact with code, it's from the command line: we craft commits, we deploy to production, we even close issues from the command line (while crafting commits). So we should also open issues from the terminal.

My first try was to use the ruby gitlab CLI, but it had several issues:

• configuration was done with environment variables
• it's written in ruby and can be complicated to install
• the output is more or less database rows in ascii tables
• you have to specify which project you're talking about

Even though I've written documentation and showed people how to use it, it was not used a lot. When a tool feels like a hack, nobody wants to use it.

What I wanted

I needed two things to get a tool people would use:

• automatically know which project we're talking about
• config files to avoid having to mess with env variables (and leak GitLab tokens)

To avoid ruby installation issues, I've decided to use Rust. There's a lot of available libraries, the build system works well, it's sufficiently expressive to let me express what I want, and in the end I get a nice binary.

XDG basedir. Respect it.

Reading GitLab credentials from a file is not really hard. One common mistake is to put config files directly in ~ like some kind of animal. Instead of cluttering users' home directories, I followed the XDG basedir spec. Most languages have a library which handles it for you, so it really is a no-brainer (and it works out of the box on Windows as well).

Infer information from context

To know where the issues should be opened, issues-helper looks at the origin remote of the current git repo. From that, it knows what to do. Even if you're not currently in the right repo,

j my-project # autojump is great
gli o "My issue" # that's it

Tools. Open Source them.

Once I had this working, not only people started using this tool, but people improved it: @keruspe fixed a lot of issues quite quickly. So the next step was to un-hardcode every Clever Cloud specific things in the codebase (then rebase everything, fun afternoon).

Once it was on GitHub, I got more contributions (from inside and outside). Also, it made me add GitHub support: not being able to use issues-helper to manage its own issues quickly got very frustrating.

Supporting GitHub also made me contribute on the GitHub crate, thus closing a vertuous circle.

There are a few issues left. Feel free to chime in, I'll help you get started. It's a good way to start working on a Rust project!

How it's done

The tool itself doesn't hold a lot of business logic. It parses a project location from a git remote, reads config from a file, sends a few HTTP requests and displays useful information.

CLI arguments parsing

It's one of the most important parts of a program, since it's the UI. The Rust ecosystem has clap which handles everything: parsing, help and even autocompletion.

Unfortunately, the parsed values are exposed through a Map<String,String>, so even though parsing checks structure, you have to recreate the structure yourself. In practice, you end up with a bunch of value.unwrap(); // this should never fail.

Fortunately, there's Structopt, which generates clap config from Rust data structures: all the dirty stuff is handled for you, and you get nice structs and enums. Yay!

Config files

Config is in a toml file, config file location is handled by the xdg crate. Remember: every time you add files to ~, a cute puppy dies.

So

Having processes in a team is a good thing, but if you don't document them, you can't expect people to respect them. If processes don't make everyone's life easier, you can't expect people to respect them. One simple way to make processes stick is to provide tooling to make them the easiest path. A bash script is cool, but mainly for its author. A stable CLI tool with a good UI, written in a robust language is not a lot of work and will age way better.

Post illustration: The Sorcerer's Apprentice, Disney Movies. Friden calculating machine. Credits: Disney

At Clever Cloud we often go to conferences, we answer many CFPs and some of us are even organising conferences from time to time. As such, we understand the amount of work required to manage these.

Just like organizing a conference, managing a CFP can become cumbersome. That's why people started writing new applications from scratch to handle it. Some of them chose Clever Cloud to host them of course. Among those, you will find cfp.io and the Devoxx family.

Some of you asked us if it was possible to run the one used by Devoxx. In this post I will show you how to deploy it on Clever Cloud.

Setup

The application is written in Scala and is based on Play Framework:

Play Framework makes it easy to build web applications with Java & Scala. Play is based on a lightweight, stateless, web-friendly architecture. Built on Akka, Play provides predictable and minimal resource consumption (CPU, memory, threads) for highly-scalable applications.

You will find the code on our good friend Nicolas Martignole's Github account. Take a look at the Readme if you want to run the application locally first. You will see that it needs to write on disk, to store data on Redis, and can optionally benefit from fulltext search with Elastic and accounts on several external services. Don't worry, you don't need everything from the start.

If you want to tag along, make sure you have Git, a Clever Cloud account and that you have installed our CLI Clever-Tools. Let's start:

• Clone the project: git clone https://github.com/nicmarti/cfp-devoxx
• Get in the project: cd cfp-devoxx
• Create the Redis add-on: clever addon create redis-addon --plan s --region eu redisCFP
• Create the FS Bucket add-on: clever addon create fs-bucket --plan s --region eu fsCFP
• Create the application: clever create --type sbt MyCFP
• Link the Redis add-on: clever service link-addon redisCFP
• Link the FS Bucket add-on: clever service link-addon fsCFP
• Define where to mount our FS Bucket: clever env set CC_FS_BUCKET /devoxx-content:`clever env | awk -F = '/BUCKET_HOST/ { print $2}'`
• Remove the old FSBucket configuration: git rm clevercloud/buckets.json && git commit -m"remove old bucket configuration"
• Copy the production configuration sample: cp conf/redis-sample-prod.conf application.conf
• Add your changes and commit them: git add application.conf;git commit -m"add default conf"

We now have to configure the application using environment variables, here is my dummy test configuration:

ACTIVATE_FAVORITES=true
ACTIVATE_GOLDEN_TICKET=false
ACTIVATE_HTTPS=true
ACTIVATE_VOTE=true
APP_SECRET=1f0bc136-5c99-1e6-bee8-60f81dae2bbc
BITBUCKET_PASSWORD=foobar
BITBUCKET_URL=https://bitbucket.org/api/1.0/repositories/foo/bar/issues
BITBUCKET_USERNAME=foobar
BUCKET_ROOTFOLDER=/app
CC_FS_BUCKET=/devoxx-content:bucket-35ca2d97-ff0e-42fb-ba37-abb815fb90a1-fsbucket.services.clever-cloud.com
CFP_HOSTNAME=app_a6dcb49e-1e16-4e06-8f45-dc9e0e838959.cleverapps.io
CFP_IS_OPEN=false
CFP_LANG=en
CRON_DAYS=2
CRON_UPDATER=false
DIGEST_DAILY=08:00
DIGEST_WEEKLY=1
ENABLE_METRICS=true
ES_ADDON_PASSWORD=foobar
ES_ADDON_URI=http://elasticsearch:9200
ES_ADDON_USER=foobar
GITHUB_ID=foobar
GITHUB_SECRET=foobar
GOOGLE_ID=foobar.apps.googleusercontent.com
GOOGLE_SECRET=foobar
JAVA_VERSION=8
LINKEDIN_CLIEND_ID=foobar
LINKEDIN_SECRET=foobar
MAIL_BCC=foobar@devoxx.fr
MAIL_BUG_REPORT=foobar@devoxx.fr
MAIL_COMMITTEE=foobar@devoxx.fr
MAIL_FROM=foobar@devoxx.fr
OPSGENIE_API=TOD
OPSGENIE_NAME=foobar
PORT=8080
SMTP_HOST=in-v3.mailjet.com
SMTP_MOCK=true
SMTP_PASSWORD=foobar
SMTP_PORT=587
SMTP_SSL=false
SMTP_USER=foobar

You can copy/paste this in the Environment variables tab of your application using the Expert Mode. Make sure you set the value of CFP_HOSTNAME to your domain name; Clever Cloud will assign one by default: take a look at the Domain Names tab in our web console to see it or change it (or use clever domain).

And that's it, your configuration is done. The next step is to deploy your application by running clever deploy.

What's next?

Your application should be running now. You can run clever open to make sure it is. It will open it in your default browser.

Now, you can start tweaking the configuration of your application. You can start by looking at all those environment variables if you have not already. There is one point where you will probably ask yourself how to get SMTP crendentials or an Elasticsearch instance from Clever Cloud. While we currently don't have any partnership with e-mails providers, you can ping our support team for the Elastic instance. It's currently in private beta and should soon be open to the public.

If you are looking for more documentation, I invite you to check out the Github repository issues and to give a good look at the production configuration file conf/application.conf.prod. I believe some of them are not mandatory. It would be great to have a documentation update just for the environment variables.

If you are going to use this for your conference, remember to activate autoscaling: clever scale --min-instances 1 --max-instances 2. And if you dread the weekend before your CFP closes, increase the number of minimum instances with clever scale --instances 2.

Post illustration: Computer at her work with microscope and the Friden calculating machine. Credits: NASA