You must write a README. This is not optional. It is where everyone begins to understand your software. Yourself included.
Who: You are writing the README for future readers. Yourself included. "Who is responsible for the README?" is a question which will be answered in the end.
You need a place to keep your README. That place is a git repository.
Do not keep code on your local machine.
If it took you longer to type the code than it would take you to git init
, it’s worthy of a home.
As with all the rest of these steps, a git repository is a gift to your future users. Even if your only future user is Future You.
Don’t write a line of code until you have a README. The README for empty repositories serves two purposes:
(1) It declares what this project is (or will be). This is a helpful mental exercise. Writing down your intentions is not the same as mentally declaring them to yourself.
(2) It declares how to use this project. Is it an app? How can I install it? Is it a service? How do I deploy it? Is it a library? How can I use it? It’s okay if you don’t have answers to these questions yet. It’s more important that you are asking the questions of yourself.
Unlicensed code is not open source. If you aren’t sure, just pick MIT. MIT is the most liberal license there is. ("Public Domain Licenses" are not licenses.) You can always change your mind later.
If building your software is more complicated than running make
, put it in the README.
If deploying your software is more complicated than running deploy
, put it in the README.
Try to make it less complicated.
"Continuous Integration" might just be "I run make
every time I git pull
."
A CI server is nice, though.
If a robot can’t run your build, you’ve probably made it too complicated.
"Continuous Deployment" might just be "I run deploy
every time the tests pass."
(Whatever "deploy" means for you.)
A CD server is nice, though.
If a robot can’t deploy your code, you’ve probably made it too complicated.
This step answers the question "how can I install it?" The details are not important.
You use git because it is an (almost) immutable, distributed ledger. Ledgers are for audits.
You write a README because it is the keystone of your documentation. Documentation is for understanding.
You write deployment (installation / consumption) instructions because you want someone to use your software. Only software that is used has any value.
You write code to automate because it is simple, easy, and possible. Everyone prefers easy, simple things.
This line of thinking puts the end at the beginning. Terms like "continuous integration", "continuous delivery", "trunk-based development", "devops", and a hundred other buzzwords all mean only this. Put the end at the beginning. You’ll be more successful that way.
Ostensibly, these rules are for new developers on your team. Battle-hardened developers always start with a README. If you don’t start with a README, if this all doesn’t seem painfully obvious to you, then you probably haven’t seen many battles yet. That means you are a new developer.
That’s okay.
In reality, these rules are for the old developers on your team. Is that you? Answer these questions: Do I have the deploy keys? Do I have the passwords? Do I have the AWS credentials? Do I have the admin account for the DNS service? If the answer is "yes" then you are an old developer. And the responsibility lies with you. No one else. It is not the responsibility of the new developers to beg for processes and keys they don’t know exist yet. It is the responsibility of the old developers to help the newer folks through this process. Step one: Give the new folks this document. Make them read it. Step two: Give them the tools and processes they need to complete the HOW section in its entirety. Step three: Begin.
CC0. Please remix this document and make it more fun so people will listen.