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:

Ensure all dependencies are present, through Bundler, Bower or NPM.

Check if system has all external dependencies required by the project (like
PostgreSQL, Redis, PhantomJS), and if they are in the minimum required version
if necessary.

Check if project’s platform/language are installed.

Copy sample database.yml, secrets.yml or .env files to ensure that the
application will boot as expected.

Ensure that a local database is present and its schema is up to date.

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:

.ruby-version to lock the Ruby version that the app depends on.

.phantom-version to lock the PhantomJS version used to run the acceptance
tests that rely on a JavaScript environment.

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

.scss-lint.yml for the [scss-lint]
(https://github.com/brigade/scss-lint) gem.

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.

This website is licensed through the Creative Commons Attribution-ShareAlike 3.0 license.