February 8, 2019

Starting an awesome list

Awesome lists are ... awesome. Let's go through the process of setting up one from scratch.

Starting an awesome list

We decided to create an awesome list for for making the Fab Academy students life a little easier and gather all the collective wisdom in one place.

This is my log about the process, might turn useful in case you need to do a similar thing.

The result of this tutorial is on Github: awesome-fabacademy

What is awesome?

Let's start to see what an Awesome list is first.  It is basically a curated collection of links on a specific topic, all collected in a single Markdown document, hosted on Github.

People can contribute to the list by sending "Pull requests" that get incorporated to the list once their quality is assessed by the list creator(s).

According to the Awesome Manifesto "Only awesome is awesome" and all links should be motivated by the proponent explaining why the link is relevant ... and awesome.

Awesome lists are very popular today, and the starting project is just one of the collections of collections available. A more extensive one is Awesome Awesomeness, and i doubt it is the largest one.

Studying existing Awesome lists helps define a style for our own. So I went trough a couple of them and collected the elements which are shared my most lists:

  • Awesome title: in this case could be Awesome-Fabacademy
  • A license: CC0 “No Rights Reserved”, that puts the list in the public domain, used by Europeana and MoMA for their collections
  • Contribution guidelines: describe how to contribute both content-wise and technically through Git pull requests
  • A code of conduct: it's not mandatory but recommended to use the Contributor Covenant statement
  • Styling the content: including a table of contents, making the contents consistent
  • The manifesto recommends also to add a badge linking to awesome.re
[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)
[![Awesome](https://awesome.re/badge-flat.svg)](https://awesome.re)
[![Awesome](https://awesome.re/badge-flat2.svg)](https://awesome.re)

Awesome
Awesome
Awesome

Setting up the list

Technically there are many ways to setup a list, one could be starting from an existing well prepared list, editing out all the links and references for the new one. Of course one could also create the files from scratch.

The third option, which I'm going to use is a Yeoman generator, a scaffolding tool that allows to quickly start web projects. There's a specific generator-awesome-list that simplifies the process.

Setup Yeoman and generator:

npm install -g yo generator-awesome-list

Create a folder and run the generator:

mkdir awesome-fabacademy
cd awesome-fabcademy
yo awesome-list

Then answer the questions on screen to generate the project:

The list is ready to be edited, and the generator prepared for us:

  • .gitattributes:  helping git to diff the changes easily, ignoring spaces
  • code-of-conduct.md: generated by the contributor covenant
  • contributing.md: contribution guidelines
  • readme.md: the actual awesome list

All the files go under version control so let's init a git repository and add all files for starting:

git init 
git add .
git commit -m 'initial import'

Setting up the Github project

Now follow the instructions and setup the Git repository as a remote for the local one. Finally push the content for the first version.

git remote add origin git@github.com:Academany/awesome-fabacademy.git
git push origin master

Formatting the list

The list comes already formatted and contains all the necessary text:

Time to start populating the readme with links. But first edit the contribution-guidelines.md. Search for this text and replace it with something more useful

Ensure your pull request adheres to the following guidelines:

Make sure you take care of this
And this as well
And don't forget to check this
Thank you for your suggestions!

I changed it like this:

Ensure your pull request adheres to the following guidelines:

- All links are relevant, valid and well described
- Commercial products are marked as such, possibly including the street price
- For any commercial product inserted, make sure you add open source software and hardware alternatives

I also pulled in some content from the original Awesome project on how to submit a pull request.

See the complete file here.

While we can't ensure that awesome list links must be valid at all time, we can check this every time the list is edited via a pull request.

I'm going to setup a CI tool, in this case Travis, to run a test on every pull request so we can check if a contribution can be accepted, but also get notified if some of the existing link break.

Links will be validated by a Ruby gem called awesome_bot, testing them using the following .travis.yml

language: ruby
rvm:
  - 2.2
before_script:
  - gem install awesome_bot
script:
  - awesome_bot readme.md --allow-redirect -w vimeo.com

Once you have this in the github repository, you can register on https://travis-ci.org/, look for your project and activate Travis builds for it.

As soon as you will push your next commit Travis will be notified an run the awesome_bot over the readme:

0.41s$ awesome_bot readme.md --allow-redirect -w vimeo.com
> Checking links in readme.md
> Will allow redirects
> White list links matching: vimeo.com 
Links to check: 8, 0 white listed, 5 unique
  1. https://awesome.re/badge.svg 
  2. https://awesome.re 
  3. http://example.com 
  4. http://mirrors.creativecommons.org/presskit/buttons/88x31/svg/cc-zero.svg 
  5. http://creativecommons.org/publicdomain/zero/1.0 
Checking URLs: ✓→→✓✓
Issues :-(
> Links 
  All OK ✓
> Dupes 
  1. [L16] http://example.com
Wrote results to ab-results-readme.md.json
Wrote filtered results to ab-results-readme.md-filtered.json
Wrote markdown table results to ab-results-readme.md-markdown-table.json
The command "awesome_bot readme.md --allow-redirect -w vimeo.com" exited with 1.

In this case with the scaffolded readme, the link check will fail since there's a duplicated link to http://example.com.

You can disable the duplicate link check using the --allow-dupe option, but I think I'll keep it.

Last thing I want to add a badge for the Travis build, so it shows in the Readme if the build is failing. This comes as an image to be linked in the readme itself:

![Travis build status](https://travis-ci.org/Academany/awesome-fabacademy.svg?branch=master)

Handling contributions

Contributions are sent via pull requests. They will also trigger a Travis build so one can check if they break something.

Next steps

The first step of course will be to fill in content. My idea is to organize the list into main topics, i.e. Project management, then add subsections for content categories, like tutorials, resources, software, books, cheatsheets.

On the repository setup, there are a few improvements to be made. I plan to add:

  • A template for pull requests, need to investigate how this is usually done
  • A system to report back any error coming from Travis directly into the Gitlab interface. I think Danger, a tool for code reviews  could help, but need to investigate more.

References