Bootstraping new projects requires a set of artifacts (scripts and configuration files) to help the onboarding of new developers into the codebase and improve the development experience as the project grows.
To help new developers get started with a project and ensure the minimal set of application dependencies is in place, it is highly recommended to include a standalone script, responsible for checking and installing dependencies, bootstraping configuration files and handling environment details, so the project can be executed and tested without manual setup.
We follow Rails’ convention of the
bin/setup for this job, and most setup
scripts do the following tasks:
.envfiles to ensure that the application will boot as expected.
For runtime/external dependencies that have a version manager available (like
rbenv or phantomenv),
we recommend adding a
.*-version file to the root of each application’s
directory to lock the dependency version and document which version is oficially
required to run the app.
In most projects is expected to find:
.ruby-versionto lock the Ruby version that the app depends on.
Projects that rely on a source code linter like RuboCop or ESLint should include the linter configuration files so developers know which standards the code should follow, be able to run the checks locally through their terminal or text editor and update these configurations as necessary by the project.
The following examples can be used as a starting point for the configurations of your project
.rubocop.ymlto lint Ruby code through RuboCop.
.scss-lint.ymlfor the [scss-lint] (https://github.com/brigade/scss-lint) gem.
Most projects have a build agent responsible for running tests and building artifacts as the new changes are pushed upstream, and the configuration for these agents should live as close as possible to the source code and be stored under the same version control repository as the project.
When using services that don’t provide this configuration approach or when using
Jenkins and/or Janky, an executable script should be used instead of configuring
the build details directly through a web UI, outside the project’s repository.
We reserve the
script/cibuild executable for this task.
All these artifacts will require continuous maintenance and updates as the project moves forward, since dependencies will be added or removed, the tooling might change and parts of the documentation will be outdated.