I was asked the other day to review the code for an application a developer I’m mentoring works on. Having just got access to his GitHub repository, this was my first time looking at his code.
Immediately, I was stuck. This was a Laravel app, that I knew, but I didn’t know how to get the application up and running, as it only had the default README file.
A README file provides easy to find instructions for your project. If you’re using GitHub, it’s displayed as the default page when you visit your repository. The file can be a plain text file, or a Markdown (.md) file if you want to give it more formatting.
What should a good README file contain?
Every project is different, but here are a few things that I like to see in a good README file.
Project Description
Tell me what this project is. Whether it’s a private repository in a company that I’m working for, or an open source project I want to work with, a quick description of what the project is can be a big help to new users.
Link to Project Website and Documentation
If this project has a website associated with it, link to it from the README file. If the project has documentation available somewhere, link to it. It could be a Wiki, a Confluence space, or maybe a Google Drive folder.
Development Environment Setup
Every project has it’s unique set up instructions when it comes to getting the developer’s local environment working properly. Ideally every developer on a project is using the same development environment, and that should be documented in the README.
This is the single biggest helpful thing to have in the README, even if you’re a solo developer. There has been many times I’ve gone back to an old project, and spent too much time trying to get it running again.
Think of:
- The required tools
- Steps to install and build application
- How to seed your database with test data
- If there are default logins, what are they?
- How to run automated tests (you have automated tests, right?)
Branching Structure
There are many different ways of managing branches in a Git repository. Document the key branches in your code.
It’s likely that main is your default branch, but if not, list it. Do you create all your pull requests against a develop branch? Maybe you have a staging branch to test things before release.
Deployment Instructions
If the project is represents a deployed application, how do you deploy changes? Are you copying files using SFTP ? Do you have a CI/CD pipeline that does the deployment as soon as you commit to main ? Do you need to tag the commit in order to release it?
Security
If you find a security issue with this project, how do you report it?
Many projects have a separate process for reporting security concerns than they do for bug reports. This is because you want to give project owners a chance to fix security issues before they get posted to public bug trackers – a process known as responsible disclosure (or coordinated disclosure). The security process is often a dedicated email address that can be contacted for this purpose.
Licensing
If there is any license agreements (MIT, GPL, Postcardware, etc.) related to this project, it should be identified here.
Contributing
If this is an open source project, how should one contribute? Is there a guide to how the community works on this project together?