From dc2350aa898c599fc43f7bebc28ba446e97ed865 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 25 Nov 2025 00:01:17 +0000 Subject: [PATCH] feat: add descriptive documentation to docs folder Created a `docs/` directory with the following descriptive markdown files: - `README.md`: Overview and index. - `getting-started.md`: Basic usage guide. - `configuration.md`: Detailed inputs and environment variable reference. - `architecture.md`: Explanation of the modular design and sub-actions. - `stacks.md`: Information on supported stacks (Wails v2, Deno). Also updated the root `README.md` to include a link to the new documentation directory. --- README.md | 3 +++ docs/README.md | 15 +++++++++++ docs/architecture.md | 32 ++++++++++++++++++++++ docs/configuration.md | 58 +++++++++++++++++++++++++++++++++++++++ docs/getting-started.md | 60 +++++++++++++++++++++++++++++++++++++++++ docs/stacks.md | 34 +++++++++++++++++++++++ 6 files changed, 202 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/architecture.md create mode 100644 docs/configuration.md create mode 100644 docs/getting-started.md create mode 100644 docs/stacks.md diff --git a/README.md b/README.md index 6829380..f0dc183 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,9 @@ [![CI](https://github.com/snider/wails-build-action/actions/workflows/ci.yml/badge.svg)](https://github.com/snider/wails-build-action/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-EUPL-green.svg)](LICENSE) +> [!NOTE] +> For comprehensive documentation, please visit the [docs](docs/) directory. + > I help on lots of open source projects, im tired of doing the same thing over and over again.\ > so, I'm going to put them all together in one place.\ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e376450 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +# Documentation + +Welcome to the documentation for `snider/build@v3`. This repository contains a modular build action for multi-stack projects, primarily focused on Wails v2 but designed to be extensible. + +## Contents + +- [Getting Started](getting-started.md) - Learn how to use the action in your workflows. +- [Configuration](configuration.md) - Detailed reference for inputs and environment variables. +- [Architecture](architecture.md) - Understand the modular design and sub-actions. +- [Stacks](stacks.md) - Specific information about supported stacks (Wails v2, Deno, etc.). + +## Quick Links + +- [Root README](../README.md) +- [Action Definition](../action.yml) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..373764d --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,32 @@ +# Architecture + +`snider/build@v3` is designed as a modular, multi-stack build system. + +## Overview + +The root action acts as a gateway. It performs discovery and then delegates the heavy lifting to specialized sub-actions. + +1. **Discovery**: Scans the repository to identify the OS, architecture, and project type (stack). +2. **Orchestration**: Decides which specific build pipeline (stack) to run. +3. **Setup**: Installs dependencies (Go, Node, Deno, etc.) based on the selected stack or configuration. +4. **Build**: Compiles the application. +5. **Sign**: Signs the binaries (if configured). +6. **Package**: Archives the output and uploads it as an artifact (and release asset on tags). + +## Directory Structure + +- `actions/` + - `discovery/`: Detects environment and project metadata. + - `options/`: Computes build options (e.g., tags). + - `setup/`: Orchestrates dependency installation. + - `go/`, `npm/`, `deno/`, `conan/`: Specific setup actions. + - `build/`: Contains stack-specific build logic. + - `wails2/`: Logic for Wails v2 builds. + - `sign/`: Unified signing for macOS and Windows. + - `package/`: Handles artifact upload and releases. + +## Design Principles + +- **Modular**: Each step is a separate composite action. You can use them individually if needed. +- **Smart Defaults**: The system tries to guess the right thing to do (Auto-Stack, Auto-Setup) but allows full override. +- **CI Gating**: The repository includes self-tests that run sub-actions to ensure stability. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..83d1c39 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,58 @@ +# Configuration + +This document covers the inputs and configuration options for the `snider/build@v3` action. + +## Action Inputs + +These inputs are defined in `action.yml` and are passed to the `with` block in your workflow. + +| Input | Description | Required | Default | +| :--- | :--- | :--- | :--- | +| `build-name` | The name of the binary or app bundle. | **Yes** | - | +| `build-platform` | Target platform (e.g., `linux/amd64`, `windows/amd64`, `darwin/universal`). | No | `darwin/universal` | +| `build` | Whether to run the build step. | No | `true` | +| `package` | Upload artifacts and publish release on tags. | No | `true` | +| `sign` | Enable platform signing (if configured). | No | `false` | +| `app-working-directory` | Root directory of the app being built. | No | `.` | +| `AUTO_STACK` | Allow auto-selection of stack based on discovery. | No | `true` | +| `AUTO_SETUP` | Allow sub-setup enabling based on env toggles. | No | `true` | +| `STACK` | Explicitly override the stack (e.g., `wails2`). | No | `""` | + +## Environment Variables + +The action uses environment variables for certain configurations, particularly for sub-actions like Deno setup. + +### Deno Configuration + +You can configure Deno usage via environment variables. These take precedence over inputs in the setup phase. + +| Variable | Description | Example | +| :--- | :--- | :--- | +| `DENO_ENABLE` | Explicitly enable Deno setup. | `true`, `1`, `on` | +| `DENO_BUILD` | Full command to run for Deno build. | `deno task build` | +| `DENO_VERSION` | Version of Deno to install. | `v1.44.x` | +| `DENO_WORKDIR` | Working directory for Deno command. | `frontend` | + +### Example with Environment Variables + +```yaml +steps: + - uses: actions/checkout@v4 + - uses: snider/build@v3 + env: + DENO_ENABLE: 'true' + DENO_VERSION: 'v1.44.x' + DENO_WORKDIR: 'frontend' + DENO_BUILD: 'deno task build' + with: + build-name: wailsApp + build-platform: linux/amd64 +``` + +## Orchestration Control + +You can control how the action delegates tasks. + +- **Auto-Stack**: By default (`AUTO_STACK: true`), the action tries to detect if you are building a Wails v2 app, etc., and uses the appropriate sub-action. +- **Auto-Setup**: By default (`AUTO_SETUP: true`), the orchestrator looks at environment variables to decide if it should set up Go, Node, Deno, etc. +- **Manual Stack**: Set `STACK: wails2` to force the Wails v2 pipeline, ignoring auto-detection. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..6a02d81 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,60 @@ +# Getting Started + +This guide will help you get started with the `snider/build@v3` action. + +## Basic Usage + +The simplest way to use this action is to let it auto-detect your project type. + +```yaml +steps: + - uses: actions/checkout@v4 + - uses: snider/build@v3 + with: + build-name: myApp + build-platform: linux/amd64 +``` + +This configuration will: +1. Detect your project stack (e.g., Wails v2). +2. Set up the necessary environment (Go, Node.js, etc.). +3. Build your application. +4. Package the artifacts. +5. Upload artifacts (and publish release on tags). + +## Common Examples + +### Build Only (No Packaging) + +If you only want to verify the build without uploading artifacts: + +```yaml +- uses: snider/build@v3 + with: + build-name: myApp + build-platform: linux/amd64 + package: false +``` + +### macOS Build + +```yaml +- uses: snider/build@v3 + with: + build-name: myApp + build-platform: darwin/universal +``` + +### Windows Build + +```yaml +- uses: snider/build@v3 + with: + build-name: myApp + build-platform: windows/amd64 +``` + +## Next Steps + +- Check [Configuration](configuration.md) for more advanced options. +- Read about [Stacks](stacks.md) for specific stack details. diff --git a/docs/stacks.md b/docs/stacks.md new file mode 100644 index 0000000..fc94cff --- /dev/null +++ b/docs/stacks.md @@ -0,0 +1,34 @@ +# Stacks + +This action supports multiple stacks, with Wails v2 being the primary one currently. + +## Wails v2 + +This is the default stack. It handles the complete lifecycle of a Wails v2 application. + +- **Detection**: Automatically detected if `wails.json` is present (logic in `discovery`). +- **Setup**: Installs Go, Node.js, and the Wails CLI. +- **Build**: Runs `wails build` with appropriate flags for the target platform. +- **Signing**: Supports macOS code signing and notarization (requires secrets) and Windows signing. + +For detailed documentation on Wails v2 inputs and usage, refer to: +- [Wails v2 Wrapper README](../actions/build/wails2/README.md) +- [Wails Build Sub-action README](../actions/build/wails2/build/README.md) + +### macOS Code Signing + +Detailed instructions for setting up macOS code signing (Certificate, Notarization) can be found in the [Wails v2 README](../actions/build/wails2/README.md). + +## Deno + +Deno support is integrated into the setup phase and can be used alongside other stacks or independently. + +- **Enable**: Set `DENO_ENABLE: true` or define `DENO_BUILD`. +- **Usage**: Useful for running frontend build steps before the main application build. + +For more details, see [Deno Setup README](../actions/setup/deno/README.md). + +## Future Stacks + +- **Wails v3**: Planned support once upstream stabilizes. +- **C++**: Placeholder support exists via `conan` setup action.