CONTRIBUTING.md

Getting Started

• Read this guide (including the Code of Conduct)
• Check out our Trello page to see what features and fixes are planned
• Fork this repository and clone your fork locally
• Setup your environment to use development tasks (test, lint, etc...)
• Adhere to the project standards
• Write some code and stuff
• Push your changes and create a pull request

Code of Conduct

Please read and adhere to the code of conduct

Introduction

First off, thank you for considering contributing to Gold!

If you would like to make a feature request or enhancement suggestion, please open an issue.

If you would like to generously provide a pull request to correct a verified issue, please adhere to this project's standards. Before making a pull request for a desired feature, please socialize the concept by opening an issue first.

Project Architecture

🚧 UNDER CONSTRUCTION

Image Design

Note

Images are built using GitHub Actions and deployed to the Github Container Registry, ghcr.io, under the username, jhwohlgemuth

The following images are available:

• ghcr.io/jhwohlgemuth/dev: Core image with all necessary system dependencies (intended for development)
• ghcr.io/jhwohlgemuth/notebook: Images with Jupyter notebook server and code-server services managed by s6-overlay
• ghcr.io/jhwohlgemuth/web: Web development environment and Verdaccio proxy npm registry ¹
• ghcr.io/jhwohlgemuth/rust: Environment ready for writing Rust code and working with WebAssembly
• ghcr.io/jhwohlgemuth/gold: Proof assistants, provers, and other tools for software correctness

The images are build according to the following dependency graph:

graph LR
    dev --> notebook
    notebook --> web
    notebook --> rust
    rust --> gold

Loading

Project Setup

🚧 UNDER CONSTRUCTION

Requirements

• Docker and/or Podman
• dos2unix
  • Format scripts for execution within a Unix environment
  • Used in Makefile format and build-image tasks
• hadolint
  • Analyze Dockerfiles
  • Configured via .hadolint.yaml
• yamllint
  • Analyze YAML files
  • Configure via .yamllint
• checkov
  • Provides more checks for Dockerfiles and YAML files
  • Checks are security focused
  • Configure via .checkov.yaml
• shfmt
  • Format shell scripts
  • Configured via .editorconfig
• shellcheck
  • Analyze shell scripts

Project Standards

• Code changes should never ² introduce issues detected by make lint or make check
• When in doubt, write code consistent with preponderance of existing codebase. Let's call this the "priority of pre-existing preponderance (P3) rule".
• Exceptions to any of these standards should be supported by strong reasoning and sufficient effort

---

Footnotes

[1]

Default Verdaccio proxy npm registry port is 4873 (documentation)

[2]

"Never" is strong language. Sometimes you might need to accept an issue or skip/ignore it. BUT, you should always have a good reason for doing so and such scenarios should be few and far between.