We’re introducing calendar-based versioning for our REST API, so we can keep evolving our API, whilst still giving integrators a smooth migration path and plenty of time to update their integrations.
At GitHub we have a lot of software running our product and company. We also have a lot of potential contributing members. Being able to get from
git clone to an up-and-running project in a development environment is imperative for fast, reliable contributions. A consistent bootstrapping experience across all our projects reduces friction and encourages contribution.
With practically every software project, developers need to perform the following tasks:
- run tests
- run continuous integration
- start app
At GitHub, we have normalized on a set of script names for all of our projects that individual contributors will be familiar with the second after they clone a project. We call them “Scripts to Rule Them All”.
Here’s a quick mapping of what our scripts are named and what they’re responsible for doing:
script/bootstrap– installs/updates all dependencies
script/setup– sets up a project to be used for the first time
script/update– updates a project to run at its current version
script/server– starts app
script/test– runs tests
script/cibuild– invoked by continuous integration servers to run tests
script/console– opens a console
Each of these scripts is responsible for a unit of work. This makes them composable, easy to call from other scripts, and easy to understand.
script/bootstrap is only responsible for dependency management.
script/setup initially calls
script/bootstrap and then has its own code that will set a project to an initial state.
script/test can be called on its own in a development environment to run tests, but is also called by
script/cibuild by our CI server.
script/console will load a development console on its own, but if appended with an environment name, will load the console for that environment.
Another advantage of consistent script names is language agnosticism. This means the scripts themselves can be written in whichever language is appropriate for the maintainers or the project. It also means the conventions can work for projects of varying languages and frameworks. This ensures an individual contributor can do things like bootstrap or run tests without knowing how to do them for a wide range of project types.
script/bootstrap might call
carthage bootstrap, or
git submodule update.
Normalizing on script names not only minimizes duplicated effort, it means contributors can do the things they need to do without having an extensive fundamental knowledge of how the project works. Lowering friction like this is key to faster and happier contributions.
We’ve created github/scripts-to-rule-them-all as a home for this pattern. In this repository, you’ll find working examples of scripts that make use of this technique as well as more detailed responsibilities of each script.