Introduction

This document forms the Cardano Engineering Handbook, which aims to provide documentation and policy that applies to all projects in the Cardano Open Source Consortium (COSC). To avoid confusion, projects should explicitly subscribe to the Handbook.

The target audience for the Handbook is everyone working on a project owned by the COSC. This is also the set of target contributors for the Handbook! Anyone can submit a change proposal as a PR, see CONTRIBUTING for the process.

Purpose

The purpose of this handbook is both descriptive and prescriptive:

  • Firstly, it prescribes mandatory or optional policies that should be followed by any software project that's part of the COSC in order to be a good citizen within the eco-system.
  • Secondly, it describes practices, processes, tools, or techniques that are used across the various projects, in order to help us to learn from each other and grow towards greater consistency in how we work.

As such, it is composed of two parts:

  • Part I is about policies
  • Part II is about practices

Goals

The goals of the Handbook are to:

  • Provide a place to record decisions on topics where coordination across the engineering organization is useful.
  • Explicitly record "the way things are done" in order to minimize tribal knowledge.
  • Encourage consistency across the organization in order to minimize cognitive overheads from unnecessary differences.
  • Be open to all contributors to the Cardano Open Source Project.

These are aspirational goals: much knowledge will not be recorded here; many topics we would like to coordinate on will be difficult to get consensus on; and consistency is not always welcome or desirable. But it is important to have an open location to record this information when we do have it.

Non-goals

The following are explicitly not goals of the Handbook:

  • Enforce the following of policies which do not have widespread support amongst the Cardano developers.
    • We believe this is a bad idea which is likely to simply cause such prescriptions to be ignored. Consequently, the Handbook should only include policies that either have widespread agreement, or are essential for coordination. Even then, policies should tend towards guidelines rather than prescriptions.
  • Collect all information relating to Cardano engineering.
    • The larger the Handbook, the harder it is to maintain. For this reason we aim to keep the scope relatively tight, although we may increase it later.
  • Supersede per-project contributing guidelines.
    • All of our projects are different, and the primary documentation for the development practices of a project should be its own contributing documentation. For suitably cross-project matters, the contributing documentation may link back to this Handbook, but the Handbook will never supersede it.

Status

The Handbook is very new and will gradually acquire more content over time. The other major issue is that many policies have been adapted from IOG policies, and are therefore IOG-specific in a way that is inappropriate for the COSC as a whole. We hope to improve all of this over time!

Please consult the issue tracker to see what we're working on, and feel free to open issues for any additional problems.