Ribose Open Source Software Guidelines

This guide reflects our current development practices we have adopted for all of our open source projects. This is the Ribose fork of the thoughtbot guide. It is mostly similar with some minor adjustments.

If you are contributing to any of our open source projects then it’s highly expected that you follow this guidelines, but if you have some different opinion about any of the rules then please open an Issue for detailed discussion.

High level guidelines:

• Be consistent.

• Don’t rewrite existing code to follow this guide.

• Don’t violate a guideline without a good reason.

• A reason is good when you can convince a teammate.

General

• Best Practices

• Git Protocol

• Code Review

Ruby Development

For Ruby-based development, we use ruby-style-guide, which is based on the bbatsov-guide with some customized preferences.

Once you start a new project, please copy the contents of for_new_projects/ruby directory to your project root. Particularly, this directory contains:

• Rubocop config

• Hound CI config

• Editor config

Once everything is setup, Hound CI should comment on each of the Pull Requests whenever there is a violations, and please resolve before merging.

Updating guides

Ruby Development

Source guides for Ruby are kept in src/rubocop. Whenever you update any of those, please run bundle exec rake build:rubocop and commit the generated changes.

Development in Other Languages

Source guides for other languages should be kept under src/${language}.

To maintainers of this guide: please update this README accordingly when guides for other languages are added.

Automatic Checks

We use several tools to measure and maintain code quality in our projects. The typical setup is:

Code Climate

Performs additional code quality analysis (complexity etc). Optionally, Code Climate is capable of running Rubocop too, however it is strongly discouraged to enable that. Due to frequent breaking changes, style guide must be written for specific Rubocop version, and our style guide is meant to be compatible with Hound. See this for respective discussion. Moreover, Code Climate is capable of measuring test coverage, however we prefer CodeCov for that.

CodeCov

Measures test coverage.

Hound CI

Runs Rubocop, that is validates code against our style guide.

GitHub Actions

Continuous integration.

Propagating guides to sister organizations

This repository is mirrored in every GitHub organization that Ribose Inc. manages in order to workaround Hound CI limitation that organization-wide style guide must be kept in a repository within that organization. Mirrors are synchronized via GitHub Actions, specifically propagate workflow defined in this very repository.

In order to set up another mirror, following steps should be performed:

1. Create a mirror repository on Github, e.g. new_organization/oss-guides.

2. Add the mirror repository to the matrix: key in the propagate.yml workflow.

3. Add the "ribose-ci" user to the new_organization/oss-guides repository with write access.

Credits

This guide is maintained by Ribose Inc.