diff --git a/.github/workflows/test-docs-scripts.yml b/.github/workflows/test-docs-scripts.yml index 2ec270b8ee..c9f4f7e24f 100644 --- a/.github/workflows/test-docs-scripts.yml +++ b/.github/workflows/test-docs-scripts.yml @@ -1,4 +1,4 @@ -name: Test Documentation Scripts +name: Documentation Scripts # This workflow tests the documentation setup scripts to ensure they work correctly. # It runs nightly and on-demand to avoid slowing down regular development workflow, @@ -14,7 +14,7 @@ on: # Allow manual triggering for testing jobs: - test-system-setup: + ubuntu: name: Test System Setup Scripts (${{ matrix.os }}) runs-on: ${{ matrix.os }} # Only run if the event is scheduled, manual, or PR has test-doc-scripts label @@ -58,11 +58,61 @@ jobs: source ~/.cargo/env ./website/docs/developers/scripts/setup/format-and-lint.sh - - name: Test run tests + - name: Verify installations + run: | + echo "Verifying installed tools..." + source ~/.cargo/env + rustc --version + cargo --version + node --version + npm --version + protoc --version + sqlite3 --version + wasm-pack --version + + macos: + name: Test System Setup Scripts (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + # Only run if the event is scheduled, manual, or PR has test-doc-scripts label + # This prevents long-running tests from blocking regular development workflow + if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts') + strategy: + matrix: + os: [macos-latest] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Test system dependencies installation + run: | + ./website/docs/developers/scripts/setup/install-system-deps-macos.sh + + - name: Test Node.js installation + run: | + ./website/docs/developers/scripts/setup/install-nodejs-macos.sh + + - name: Test Rust installation + run: | + ./website/docs/developers/scripts/setup/install-rust.sh + + - name: Test WASM tools installation run: | # Source cargo environment first source ~/.cargo/env - ./website/docs/developers/scripts/setup/run-tests.sh + ./website/docs/developers/scripts/setup/install-wasm-tools.sh + + - name: Test specialised builds + run: | + # Source cargo environment first + source ~/.cargo/env + ./website/docs/developers/scripts/setup/build-specialized.sh + + - name: Test format and lint + run: | + # Source cargo environment first + source ~/.cargo/env + ./website/docs/developers/scripts/setup/format-and-lint.sh - name: Verify installations run: | @@ -76,7 +126,7 @@ jobs: sqlite3 --version wasm-pack --version - test-docker-setup: + docker-ubuntu: name: Test Docker Setup Script (${{ matrix.os }}) runs-on: ${{ matrix.os }} # Only run if the event is scheduled, manual, or PR has test-doc-scripts label @@ -98,3 +148,27 @@ jobs: run: | sudo docker --version sudo docker run hello-world + + docker-macos: + name: Test Docker Setup Script (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + # Only run if the event is scheduled, manual, or PR has test-doc-scripts label + # This prevents long-running tests from blocking regular development workflow + if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts') + strategy: + matrix: + os: [macos-latest] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Test Docker installation + run: | + ./website/docs/developers/scripts/setup/install-docker-macos.sh + + - name: Verify Docker installation + run: | + # Docker Desktop needs to be started manually on macOS + # We'll just check if it was installed via Homebrew + docker --version || echo "Docker installed but not running (expected on macOS CI)" diff --git a/.gitignore b/.gitignore index 3180192506..991de41f02 100644 --- a/.gitignore +++ b/.gitignore @@ -13,4 +13,9 @@ cargo-build-test.json tests.tsv # Generated API docs should not be committed -website/static/api-docs/ \ No newline at end of file +website/static/api-docs/ + +ledger/3.0.0devnet +ledger/3.0.0mainnet +ledger/3.0.1devnet +ledger/berkeley_rc1 \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f308a93e8..e67d7e121d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Development Tools**: Enhanced formatting infrastructure with MDX file support and trailing whitespace management ([#1234](https://github.com/o1-labs/openmina/pull/1234)) +- **Documentation**: add instructions for developers using MacOS based systems, + and test the installation commands in CI + ([#1247](https://github.com/o1-labs/openmina/pull/1234)). ### Changed diff --git a/CLAUDE.md b/CLAUDE.md index e20d5a2396..da69830a01 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -218,6 +218,55 @@ referencing Claude. 6. **Verify commit message contains no emojis and follows 80-character wrap** 7. Proceed with testing or committing changes +### Documentation Script Testing + +When modifying developer setup scripts in `website/docs/developers/scripts/`, +always test them using the documentation testing workflow: + +#### Testing Documentation Scripts + +The project includes automated testing of developer setup scripts to ensure they +work correctly across different platforms. This prevents developers from +encountering broken installation instructions. + +**When to test:** + +- After modifying any script in `website/docs/developers/scripts/setup/` +- When adding new dependencies or tools to the setup process +- When changing installation procedures +- When adding support for a new distribution or platform + +**How to trigger tests:** + +1. **For PRs**: Add the `test-doc-scripts` label to your pull request +2. **Manual testing**: Use GitHub CLI: + `gh pr edit --add-label test-doc-scripts` +3. **Remove and re-add**: If tests need to be re-run, remove the label first: + ```bash + gh pr edit --remove-label test-doc-scripts + gh pr edit --add-label test-doc-scripts + ``` + +**What gets tested:** + +- System dependencies installation (Ubuntu/macOS) +- Rust toolchain setup (including taplo, wasm-pack, etc.) +- Node.js installation +- Docker installation +- Build processes and formatting tools +- Tool version verification + +**Why this matters:** + +- Ensures documentation stays current with actual requirements +- Prevents "command not found" errors for new developers +- Tests across multiple platforms (Ubuntu 22.04, 24.04, macOS) +- Catches environment drift and dependency changes +- Runs nightly to detect breaking changes early + +The tests are designed to run on-demand via labels to avoid slowing down regular +development workflow, as they can take significant time to complete. + ### Critical Pre-Commit Requirements - **MANDATORY**: Run `make fix-trailing-whitespace` before every commit diff --git a/Makefile b/Makefile index 1d2f4d34e1..542fbe4e0d 100644 --- a/Makefile +++ b/Makefile @@ -103,7 +103,7 @@ fix-trailing-whitespace: ## Remove trailing whitespaces from all files -not -path "./website/static/api-docs/*" \ -not -path "./website/.docusaurus/*" \ -not -path "./.git/*" \ - -exec sed -i 's/[[:space:]]*$$//' {} + && \ + -exec sed -i'' -e "s/[[:space:]]*$$//" {} + && \ echo "Trailing whitespaces removed." .PHONY: check-trailing-whitespace @@ -139,7 +139,10 @@ clean: ## Clean build artifacts download-circuits: ## Download the circuits used by Mina from GitHub @if [ ! -d "circuit-blobs" ]; then \ git clone --depth 1 https://github.com/openmina/circuit-blobs.git; \ - ln -s -b "$$PWD"/circuit-blobs/* ledger/; \ + ln -s "$$PWD"/circuit-blobs/3.0.0devnet ledger/; \ + ln -s "$$PWD"/circuit-blobs/3.0.0mainnet ledger/; \ + ln -s "$$PWD"/circuit-blobs/3.0.1devnet ledger/; \ + ln -s "$$PWD"/circuit-blobs/berkeley_rc1 ledger/; \ else \ echo "circuit-blobs already exists, skipping download."; \ fi diff --git a/website/docs/developers/getting-started.mdx b/website/docs/developers/getting-started.mdx index 4ca5dcbcac..ee5566fd28 100644 --- a/website/docs/developers/getting-started.mdx +++ b/website/docs/developers/getting-started.mdx @@ -5,14 +5,18 @@ sidebar_position: 1 # Getting Started for Developers import CodeBlock from "@theme/CodeBlock"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; import InstallRustSh from "!!raw-loader!./scripts/setup/install-rust.sh"; import InstallSystemDepsSh from "!!raw-loader!./scripts/setup/install-system-deps.sh"; +import InstallSystemDepsMacOSSh from "!!raw-loader!./scripts/setup/install-system-deps-macos.sh"; import InstallNodejsSh from "!!raw-loader!./scripts/setup/install-nodejs.sh"; +import InstallNodejsMacOSSh from "!!raw-loader!./scripts/setup/install-nodejs-macos.sh"; import InstallDockerSh from "!!raw-loader!./scripts/setup/install-docker.sh"; +import InstallDockerMacOSSh from "!!raw-loader!./scripts/setup/install-docker-macos.sh"; import InstallWasmToolsSh from "!!raw-loader!./scripts/setup/install-wasm-tools.sh"; import CloneAndBuildSh from "!!raw-loader!./scripts/setup/clone-and-build.sh"; import BuildSpecializedSh from "!!raw-loader!./scripts/setup/build-specialized.sh"; -import RunTestsSh from "!!raw-loader!./scripts/setup/run-tests.sh"; import FormatAndLintSh from "!!raw-loader!./scripts/setup/format-and-lint.sh"; Welcome to OpenMina development! This guide will help you set up your @@ -22,8 +26,10 @@ development environment and build OpenMina from source. ### System Requirements -- **Operating System**: Ubuntu 20.04+ or Debian 11+ (other Linux distributions - may work but are not officially supported) +- **Operating System**: + - **Linux**: Ubuntu 20.04+ or Debian 11+ (other Linux distributions may work + but are not officially supported) + - **macOS**: macOS 12.0+ (Monterey or later) - **Memory**: At least 8GB RAM (16GB recommended) - **Storage**: At least 20GB free space - **Network**: Stable internet connection for downloading dependencies @@ -32,24 +38,64 @@ development environment and build OpenMina from source. #### 1. Rust Toolchain -OpenMina requires both stable and nightly Rust toolchains: +OpenMina requires both stable and nightly Rust toolchains, plus additional tools +for development: {InstallRustSh} +This installs: + +- Rust 1.84 (stable) and nightly toolchains +- Required components: `rustfmt`, `clippy`, `rust-src` +- `taplo-cli`: TOML formatter required for `make format` + #### 2. System Dependencies + + + {InstallSystemDepsSh} + + + +{InstallSystemDepsMacOSSh} + + + + #### 3. Additional Development Tools **Node.js (for documentation and frontend):** + + + {InstallNodejsSh} + + + +{InstallNodejsMacOSSh} + + + + **Docker (optional, for containerized builds):** + + + {InstallDockerSh} + + + +{InstallDockerMacOSSh} + + + + #### 4. WASM Tools (for web node development) {InstallWasmToolsSh} @@ -69,7 +115,11 @@ components: ### 3. Run Tests -{RunTestsSh} +You can run a different set of tests. The command `make help` will give you the +whole set of targets. You can also visit the file +[ci.yaml](https://github.com/o1-labs/openmina/blob/develop/.github/workflows/ci.yaml) +to explore the targets used for testing in our continuous integration +environment. ## Development Workflow @@ -108,12 +158,24 @@ make clean # Clean build artifacts ### Environment Configuration -Some components require environment variables: +Some components require environment variables and database setup: + +#### SQLite Database (Required for `make check`) + +The heartbeats processor requires an SQLite database to be initialized before +running `make check`: ```bash -# For SQLx database operations (heartbeats processor) +# Create the SQLite database with required schema +sqlite3 /tmp/heartbeats.db < tools/heartbeats-processor/schema.sql + +# Set the database URL environment variable export DATABASE_URL="sqlite:///tmp/heartbeats.db" +``` +#### Additional Environment Variables + +```bash # For archive node development export OPENMINA_ARCHIVE_ADDRESS="http://localhost:3007" export PG_USER="openmina" diff --git a/website/docs/developers/scripts/setup/format-and-lint.sh b/website/docs/developers/scripts/setup/format-and-lint.sh index 7888cbfa1c..f09c6f6b39 100755 --- a/website/docs/developers/scripts/setup/format-and-lint.sh +++ b/website/docs/developers/scripts/setup/format-and-lint.sh @@ -1,3 +1,8 @@ +# Set up SQLite database for heartbeats processor (required for make check/lint) +echo "Setting up SQLite database for heartbeats processor..." +sqlite3 /tmp/heartbeats.db < tools/heartbeats-processor/schema.sql +export DATABASE_URL="sqlite:///tmp/heartbeats.db" + # Format code (required before commits) echo "Formatting code..." make format diff --git a/website/docs/developers/scripts/setup/install-docker-macos.sh b/website/docs/developers/scripts/setup/install-docker-macos.sh new file mode 100755 index 0000000000..6213055d28 --- /dev/null +++ b/website/docs/developers/scripts/setup/install-docker-macos.sh @@ -0,0 +1,9 @@ +# Install Docker Desktop for Mac +# Note: This requires manual download and installation +echo "Docker Desktop for Mac needs to be installed manually." +echo "Please download it from: https://www.docker.com/products/docker-desktop/" +echo "Alternatively, you can use Homebrew Cask:" +echo "brew install --cask docker" + +# Install Docker via Homebrew Cask (user will need to start Docker Desktop manually) +brew install --cask docker \ No newline at end of file diff --git a/website/docs/developers/scripts/setup/install-nodejs-macos.sh b/website/docs/developers/scripts/setup/install-nodejs-macos.sh new file mode 100755 index 0000000000..fa90997089 --- /dev/null +++ b/website/docs/developers/scripts/setup/install-nodejs-macos.sh @@ -0,0 +1,5 @@ +# Install Node.js (version 18+ recommended) via Homebrew +brew install node@18 + +# Link Node.js if needed +brew link node@18 \ No newline at end of file diff --git a/website/docs/developers/scripts/setup/install-rust.sh b/website/docs/developers/scripts/setup/install-rust.sh index b7b8514941..52e519b10a 100755 --- a/website/docs/developers/scripts/setup/install-rust.sh +++ b/website/docs/developers/scripts/setup/install-rust.sh @@ -15,4 +15,7 @@ rustup install nightly rustup component add rustfmt clippy --toolchain 1.84 # Add required components for nightly -rustup component add rustfmt clippy --toolchain nightly +rustup component add rustfmt clippy rust-src --toolchain nightly + +# Install taplo (TOML formatter, required for `make format`) +cargo install taplo-cli --locked diff --git a/website/docs/developers/scripts/setup/install-system-deps-macos.sh b/website/docs/developers/scripts/setup/install-system-deps-macos.sh new file mode 100755 index 0000000000..7cee9dcafe --- /dev/null +++ b/website/docs/developers/scripts/setup/install-system-deps-macos.sh @@ -0,0 +1,13 @@ +# Install Homebrew if not already installed +if ! command -v brew &> /dev/null; then + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +fi + +# Install system dependencies +brew install \ + openssl \ + pkg-config \ + protobuf \ + sqlite \ + git \ + curl \ No newline at end of file diff --git a/website/docs/developers/scripts/setup/install-wasm-tools.sh b/website/docs/developers/scripts/setup/install-wasm-tools.sh index 39636a566c..db2f1c51b9 100755 --- a/website/docs/developers/scripts/setup/install-wasm-tools.sh +++ b/website/docs/developers/scripts/setup/install-wasm-tools.sh @@ -1,5 +1,8 @@ # Install wasm-pack for WebAssembly builds cargo install wasm-pack +# Install wasm-bindgen CLI tool for generating WebAssembly bindings +cargo install -f wasm-bindgen-cli --version 0.2.99 + # Add WebAssembly target rustup target add wasm32-unknown-unknown diff --git a/website/docs/developers/scripts/setup/run-tests.sh b/website/docs/developers/scripts/setup/run-tests.sh deleted file mode 100755 index a22a89c97e..0000000000 --- a/website/docs/developers/scripts/setup/run-tests.sh +++ /dev/null @@ -1,8 +0,0 @@ -# Set up environment for tests -export DATABASE_URL="sqlite:///tmp/heartbeats.db" - -sqlite3 /tmp/heartbeats.db < tools/heartbeats-processor/schema.sql 2>/dev/null || true - -# Run basic tests (excluding those that require special setup) -echo "Running basic test suite..." -make test diff --git a/website/static/img/openmina-social-card.svg b/website/static/img/openmina-social-card.svg new file mode 100644 index 0000000000..18d979943b --- /dev/null +++ b/website/static/img/openmina-social-card.svg @@ -0,0 +1,4 @@ + + + +