Hi everyone, I’m Oleg and I’m yelling at (probably your) repo.

This is a copy of my dialogue with a friend about how to make a good and helpful repo for any community of any size and any programming language.

Let’s start.

README says nothing

But it’s a crucial part of any repo!

It’s the first interaction with your potential user and this is a first impression that you might bring to the user.

After the name (and maybe a logo) it’s a good place to put a few badges like:

recent version

CI status

link to the docs

code quality

code coverage

even the number of users in a chat

or just scroll all of them on https://shields.io/

Personal fail. Not so long time ago I did a simple, hacky and a bit funny project in Go which is called sabotage. I put a quote from a song, have added a picture, but… haven’t provided any info what it does.

This takes like 10 minutes to make a simpler intro and explain what I’m sharing and what it can do.

There is no reason why you or I should skip it.

Custom license or no license at all

First and most important: DO. NOT. (RE)INVENT. LICENSE. PLEASE.

When you’re going to create a new shiny new license or make any existent much better, please, ask yourself 17 times: what is the point to do so?

Companies of any size are very conservative in licenses, ’cause it might destroy their business. So if you’re targeting big audience — it’s a dumb way to do so.

There are a lot of guides on how to select the license and living it unlicensed or using an unpopular or funny (like WTFPL) will just be a bad sign for a user.

Feel free to choose one of the most popular:

MIT — when you want to give it for free

BSD3 — when you want a bit more rights for you

Apache 2.0 — when it’s a commercial product

GPLv3 — which is also a good option

(that’s might be an opinionated list, but whatever)

No Dockerfile

It’s already 2019 and the containers have won this world.

It’s much simpler for anyone to make a docker pull foo/bar command rather than download all dependencies, configure paths, realise that some things might be incompatible or even be scared to totally destroy their system.

Is there a guarantee that there is no rm -rf in an unverified project? 😈

Adding a simple Dockerfile with everything needed can be done is 30 mins. But this will give your users a safe and fast way to start using, validating or helping to improve your work. A win-win situation.

Changes without pull requests

That might look weird, but give me a second.

When a project is small and there are 0 or few users — that might be okay. It’s easy to follow what happened last days: fixes, new features, etc. But when the scale gets bigger, oh… it becomes a nightmare.

You have pushed few commits into the master, so probably you did it on your computer and no one saw what happened, there wasn’t any feedback. You may break API backward compatibility, forgot to add or remove something, even make useless work (oh, nasty one).

When you’re doing a pull request, some random guru-senior-architect might occasionally check your code and suggest few changes. Sounds unlikely but any additional eyes might uncover bugs or architecture mistakes.

Do not hide your work, isn’t this a reason for open sourcing it?

Bloated dependencies

Maybe it’s just me but I’m very conservative with dependencies.

When I see dozens of deps in the lock file, the first question which comes to my mind is: so, am I ready to fix any failures inside any of them?

Yeah, it works today, maybe it worked 1 week/month/year before, but can you guarantee what will happen tomorrow? I cannot.

No styling or formatting

Different files (sometimes even functions) are written in a different style.

This causes troubles for the contributors, ‘cause one prefers spaces and another prefers tabs. And this is just the simplest example.

So what will be the result:

1 file in one style and another in completely different

1 with { at the end of a line and another { on the new line

at the end of a line and another on the new line 1 function in functional style and right below in pure procedural

Which of them is right? — I dunno but this is acceptable if it works but also this horribly distracts readers for no reason.

Simple rule for this: use formatter and linters: eslint, gofmt, rustfmt…oh tons of them! Feel free to configure it as you would like to but keep in mind that the most popular tend to be most natural.

No automatic builds

How you can verify that user can build your code?

The answer is quite simple — build system. TravisCI, GitlabCI, CircleCI and that ‘s only a few of them.

Treat a build system as a silent companion that will check your every commit and will automatically run formatters/linters to ensure that new code has good quality. Sounds amazing, isn’t it?

And adding a simple yaml file which describes how the build should be done in minutes, as always.

No releases or Git tags

Master branch might be broken.

That happening. This is unpleasant stuff but it happens.

Some recent changes might be merged and somehow this causes troubles on the master. How much time it will take to fix for you? few minutes? an hour? a day? Till you’ll be back from vacation? Who knows ‾\_(ツ)_/‾

But when there is a Git tag which points to the time when a project was correct and able to be built, oh, that’s a good thing to have and make the life of your users much better.

Adding release on a Github (similar as Gitlab or any other place) is literally seconds, no reason to omit this step.

No tests

Well, it might be okay.

Of course, having correct tests is a nice thing to have, but probably you’re doing this project after work in your free time or weekend (I’m guilty, I’m doing this so often instead to have a rest).

So don’t be strict to yourself, feel free to share your work and share knowledge. The test can be added later, time with family and friends is more important, the same as mental or physical health.

Conclusion

There are a lot of other things that will make your repo even better, but maybe you will mention them personally in comments?

Twitter: https://twitter.com/oleg_kovalov/status/1105719270116388864

Lobsters: https://lobste.rs/s/6gixqw/what_i_don_t_like_your_repo

HN: https://news.ycombinator.com/item?id=19376264

Reddit: https://www.reddit.com/r/programming/comments/b0isug/what_i_dont_like_in_your_repo/

Thanks.