Project Charter - input-output-hk/mithril GitHub Wiki

Foreword

This file contains the Mithril Project Charter, including but not limited to coding standards and best practices when contributing.

Core Team Golden Rules

  1. Systematically tag breaking change or manual-deployment Issues and/or PRs.
  2. Plan migrations: a/ with other teammates if support is needed and b/ run them locally or in a specific environment before merging.
  3. Merging code is not allowed from Monday to Thursday after 5pm CET, on Friday after 12pm CET and during the week-end.
  4. When merging a PR, a teammate must make sure that the merge is successfully deployed, and escalate with other teammates if needed.
  5. Teammates should be able to connect to the Mithril networks machines and operate runbooks processes.

External Contributor Process

  1. Express your interest in contributing by commenting on an issue labeled good first issue. A core team member will then assign you to the ticket.
  2. Create your fork of the main repository here.
  3. Setup your fork to run the CI workflow:
  • Configure GitHub Actions:
    • Enable Allow all actions and reusable workflows in your fork Settings / Actions / General / Actions permissions.
    • Enable Read and write permissions in your fork Settings / Actions / General / Workflow permissions.
  • Configure Code Security:
    • Enable Dependency graph in your fork Settings / Security / Code security and analysis.
  1. Create and push a new branch in your fork with your code proposal.
  2. Create a draft Pull Request in your fork from your branch.
  3. This will trigger the run of the CI workflows in the GitHub Actions of your fork:
  • You have complete control on the jobs run in your fork (e.g. restart them if they fail, ...).
  • You don't need to wait for approval from the Core team to run the CI.
  1. Enrich your Pull Request until it is ready to be reviewed by the Core Team. On new pushes to your branch, new run of the CI workflows. will be triggered automatically. Make sure that the CI is all green before moving to the next step.
  2. Create a Pull Request on the main repository from your branch.
  3. Wait for a member of the Core Team to run the CI for your PR.
  4. If the CI is all green, your PR will be reviewed and eventually merged.

Coding Standards

Rust

  • Use rustfmt to format the code before submitting a commit.

  • Use clippy to format the code before submitting a commit.

Why

It helps the team keep a clean and neat codebase and straightforward commits diffs

Git

Commit message format

Here are seven rules for great git commit messages:

  1. Separate subject from body with a blank line

  2. Limit the subject line to 50 characters (soft limit)

  3. Capitalize the subject line

  4. Do not end the subject line with a period

  5. Use the imperative mood in the subject line and suffix with ticket number if applicable

  6. Wrap the body at 72 characters (hard limit)

  7. Use the body to explain what and why vs. how

Why

Git commit messages are our only source of why something was changed the way it was changed. So we better make the readable, concise and > detailed (when required).

Thanks to the Hydra team for these Git guidelines! Hydra Wiki

Pull Request

Here are the rules we tend to apply when using PR:

  1. Name your branches properly: for example username/branch-that-does-something

  2. Prefer PR over main branch commit (they are reserved for very low impact updates and should used with parcimony)

  3. Prefer Rebase and Merge than Create a merge commit

  4. Prefer multiple atomic commits (it will facilitate the reviews)

  5. Make sure the CI is all green 🟢 and that there's no lint warnings (such as the one from clippy for Rust)

  6. Ask for reviewers (caution, they may depend on the modified directories): 1 approval is the general rule, wait for 2 or more if the impact is high

Why

Code reviews are important to share knowledge and to deliver better software quality!