Project Setup

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.

Setup script

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:

Version manager’s configuration

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:

Linter’s configuration

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

Build runner scripts and configurations

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.

In the cases where the project uses a 3rd party service like Travis CI or Circle CI, the configuration is done through a manifest file (a YAML in most cases).

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.

Ongoing maintenance

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.