If you have an attention span as short as mine, feel free to skip to the TL;DR.
By noticing them missing in a good deal of projects and the friction and occasional frustration that came with it, I have came up with a list of things I would like to have in place before I start writing even a single line of code.
This list attempts to address three questions:
- What is this project and/or what purpose does it solve?
- How does one run it or use it?
- How can one contribute?
Those are answered, I believe, by having a few essential things in place:
- A well written README file - this is the first introduction to my project, so I will put extra care to make sure it’s clear, concise, semantically, and syntactically correct.
- A script (Makefile, npm scripts) that helps run or use this project;
if it’s a library, have documentation, with copious examples of usage.
It can be part of the README - if not, the README should include a prominent link to this documentation.
- Build script and Continuous Integration - the latter is in particular so
easy to set up nowadays there’s no good excuse not to.
Include linters and style guide (e.g.
- Guidelines on how to contribute:
- call out expectations and requirements for pull requests (e.g. documentation, tests, other artifacts);
- set up templates for submitting issues and request improvements;
- Set up a code of conduct, even if I’m the only contributor. It’s something to read when I get upset or frustrated (we’re all humans);
- Publish scripts: nuget, npm, pypi all have their own preferred formats (optional but highly recommended if it’s a library);
With that in mind, here how the first 30 minutes before I write any code look like:
T-30: Head over to GitHub, Bitbucket, or GitLab and create a new repo
with a README.
.gitignore appropriate to my project as well as the license.
T-29: Clone the repo on my computer. Open the README.
T-29: Take 5 minutes to document what the project does and what problem it solves. Add links to any relevant resources (e.g. blog posts, Stack Overflow).
T-24: Set up the directory structure.
- For .NET projects, I use David Fowler’s .NET project structure
- For Python modules, I like Jean-Paul Calderon’s Filesystem structure of a Python project
- For Node modules, I use a simplified version of the .NET Project structure,
typically including the
testfolders; prominent Node frameworks follow this layout;
- For Node application (based on express, koa, etc), I like the layout proposed by Lance Pollard in this gist or in this Stack Overflow answer;
- If a framework comes with it’s own project generator (e.g. Django), I follow that project’s preferred structure.
T-23: Create a minimal build script. I use:
- Cake for .Net projects;
- For Python projects I like using the requests Makefile and Kenneth Reitz’s setup.py.
Add nodes/entries for linting (pep8, flake8, eslint) and unit testing (even if I don’t have any yet).
T-18: Go back to the README and add a section about how to run the script.
T-10: Back to the README, add the AppVeyor and Travis badges so visitors know the current status of my build.
T-9: Add support for Snyk to help with vulnerability monitoring.
T-7: If the provider support it, I spend a few minutes creating issue templates to help with reporting defects and suggest improvement; if not, document in the README the type of information needed for defects.
T-4: Consider adding contributing guidelines and adopting a Code of Conduct.
T-1: Add an
## Examples or
## Usage node to the README as a reminder
to add more documentation once the code or interfaces get fleshed-out.
T-0: Happy coding.
TL;DR / Checklist
- Repo with
.gitignore, license, and README;
- Immediately document what the project does and what problem it solves;
- Set up folder structure;
- Create minimal build script;
- Add to README instructions on how to run the build script or the project via the build script;
- Add CI integration; add badges for CI status;
- Add configuration for Snyk to help detect vulnerabilities;
- Write issue templates or document how to report issues;
- Add contributing guide lines and Code of Conduct;
- Add Examples and Usage entries in README to fill in later.