From 53dbfeda7a225893a1990cc59973c5ad091bf467 Mon Sep 17 00:00:00 2001 From: Dave Collins Date: Sun, 7 Nov 2021 16:29:37 -0600 Subject: [PATCH] primitives: Add skeleton README.md. --- internal/staging/primitives/README.md | 63 +++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 internal/staging/primitives/README.md diff --git a/internal/staging/primitives/README.md b/internal/staging/primitives/README.md new file mode 100644 index 0000000000..e9e3784bb3 --- /dev/null +++ b/internal/staging/primitives/README.md @@ -0,0 +1,63 @@ +primitives +========== + +[![Build Status](https://github.com/decred/dcrd/workflows/Build%20and%20Test/badge.svg)](https://github.com/decred/dcrd/actions) +[![ISC License](https://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) +[![Doc](https://img.shields.io/badge/doc-reference-blue.svg)](https://pkg.go.dev/github.com/decred/dcrd/internal/staging/primitives) + +## Package and Module Status + +This package is currently a work in progress in the context of a larger refactor +and thus does not yet provide most of the things that are ultimately planned. +See https://github.com/decred/dcrd/issues/2786 for further details. + +The intention is to create a containing `primitives` module that will be kept at +an experimental module version ("v0") until everything is stabilized to avoid +major module version churn in the mean time. + +## Overview + +This package ultimately aims to provide core data structures and functions for +working with several aspects of Decred consensus. + +The provided functions fall into the following categories: + +- Proof-of-work + - Converting to and from the target difficulty bits representation + - Calculating work values based on the target difficulty bits + - Checking that a block hash satisfies a target difficulty and that the target + difficulty is within a valid range + +## Maintainer Note + +Since the `primitives` module is heavily relied upon by consensus code, there +are some important aspects that must be kept in mind when working on this code: + +- It must provide correctness guarantees and full test coverage +- Be extremely careful when making any changes to avoid breaking consensus + - This often means existing code can't be changed without adding an internal + flag to control behavior and introducing a new method with the new behavior +- Minimize the number of allocations as much as possible +- Opt for data structures that improve cache locality +- Keep a strong focus on providing efficient code +- Avoid external dependencies + - Consensus code requires much stronger guarantees than typical code and + consequently code that is not specifically designed with such rigid + constraints will almost always eventually break things in subtle ways over + time +- Do not change the API in a way that requires a new major semantic version + - This is not entirely prohibited, but major module version bumps have severe + ramifications on every consumer, and thus they should be an absolute last + resort +- Take care when adding new methods to avoid method signatures that would + require a major version bump due to a new major dependency version + +## Installation and Updating + +This package is internal and therefore is neither directly installed nor needs +to be manually updated. + +## License + +Package primitives is licensed under the [copyfree](http://copyfree.org) ISC +License.