Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (101 loc) · 4.22 KB

CONTRIBUTING.md

File metadata and controls

134 lines (101 loc) · 4.22 KB

Contributing

Installation requirements

Different OS distributions have different installation requirements.

Linux:

We recommend installing the pkgconfig and liburing systems packages, though they are not required. However, one would not get the performance benefits of performing I/O asynchronously.

  • Ubuntu: 
    apt-get install pkg-config liburing-dev

If these packages are not installed, then the serialblockio cabal package flag has to be enabled, either by setting the flag in cabal.project/cabal.project.local, or by passing the flag to the cabal executable using --flag=+serialblockio.

Installing rocksdb is entirely optional, and only required if one wants to build or run the utxo-rocksdb-bench comparison macro-benchmark.

  • Ubuntu: 
    apt-get install librocksdb-dev

If this package is not installed, then the rocksdb cabal package flag has to be disabled, either by setting the flag in cabal.project/cabal.project.local, or by passing the flag to the cabal executable using --flag=-rocksdb

MacOS

There are no installation requirements.

Windows

There are no installation requirements.

Building

The project is built using ghc and cabal.

cabal update
cabal build all

Testing

Tests are run using cabal.

cabal build all
cabal test all

Code style

There is no strict code style, but try to keep the code style consistent throughout the repository and favour readability. Code should be well-documented and well-tested.

Formatting

We use stylish-haskell to format Haskell files, and we use cabal-fmt to format *.cabal files. We also use cabal check to sanity check our cabal files. See the helpful scripts in the scripts folder, and the stylish-haskell configuration file.

To perform a pre-commit code formatting pass, run one of the following:

  • If you prefer fd and have it installed on your system:

    ./format-stylish-fd.sh
./format-cabal-fd.sh
./check-cabal.sh
./haddocks.sh

  • Otherwise using Unix find:

    ./format-stylish-find.sh
./format-cabal-find.sh
./check-cabal.sh
./haddocks.sh

Pull requests

The following are requirements for merging a PR into main:

  • Each commit should be small and should preferably address one thing. Commit messages should be useful.
  • Document and test your changes.
  • The PR should have a useful description, and it should link issues that it resolves (if any).
  • Changes introduced by the PR should be recorded in the relevant changelog files. Ideally, each changelog entry should link to the PR that introduced the changes, and it should have a BREAKING, NON-BREAKING, or PATCH level.
  • PRs should not bundle many unrelated changes.
  • PRs should be approved by at least 1 code owner.
  • The PR should pass all CI checks.

Releases

Releases follow the Haskell Package Versioning Policy. We use version numbers consisting of 4 parts, like A.B.C.D.

  • A.B is the major version number. A bump indicates a breaking change.
  • C is the minor version number. A bump indicates a non-breaking change.
  • D is the patch version number. A bump indicates a small, non-breaking patch.

To publish a release for a package, follow the steps below:

  • Changelog checks (CHANGELOG.md):

    • Check that all user-facing changes have been recorded.
    • Check that each changelog entry is in one of these sections: Breaking changes, New features, Minor changes, or Bug fixes.
    • Check that each changelog entry links to a PR, if applicable.
    • Add or update the changelog's section header with the package version that is going to be released, and the date of the release. The version should be picked based on our package versioning policy.

  • Cabal file checks (*.cabal):

    • Update the version field.
    • Update the tag field of the source-repository this stanza.

  • Cabal project file checks (cabal.project*):

    • Update the index-state in the cabal.project.release file to the current date-time, or the closest valid date-time to the current date-time, so that CI builds and tests the libraries with the newest versions of dependencies.