Expectations of an open-source project
I was poking into the source code of an open source project last weekend when it occurred to me that several years working as a devops engineer has raised my expectations when it comes to making a source code repository easy to work with.
Poking into some source code this weekend got me thinking about my personal quality bar when it comes to software projects.
Let me share some expectations I have of source code in a repository.
the repository has
- a
README.mdproviding a smooth entrypoint into the project - project docs including:- a short sentance or paragraph summarizing the purpose or goal of the project
- a list of any dependencies or prerequisites
- getting started (as an end user of the code)
- getting started (as a developer in the code)
- common repetative tasks scripted into a build tool (e.g. Makefile, Rakefile, Taskfile, etc)
- any complicated setup is scripted and easy
- any dependencies between steps (e.g. must build before running the tests) are scripted so that no task fails due to missing dependencies
- passing tests
- it is okay to have a more complete or complicated set of tests that require more setup (e.g. a running web server or in-memory/local database in a specific state) but there should be a set of in-memory unit tests that are always passing
it should be easy to
- install and verify any prerequisites
- install any required code/package/library dependencies
- clean the results of all previous builds
- build the code
- validate that the code is stable (“all” tests pass; where “all” means whatever makes sense for your project but is clearly defined and easy to do)
- validate that the code is formatted correctly (e.g. linting rules)
- run the code/use the library locally to validate that it works as expected