docs: add guides and fix documentation issues
New documentation: - getting-started.md: installation, first build, first release - troubleshooting.md: common errors and fixes - workflows.md: end-to-end task sequences - glossary.md: term definitions - migration.md: upgrading from legacy tools Fixes: - Command examples: core dev task* → core ai task* - CI flag: --were-go-for-launch → --we-are-go-for-launch - Setup commands: core health → core dev health - Installation: circular core go install reference - Cross-references: broken fragment links Improvements: - Added complete repos.yaml documentation - Added comprehensive environment variables reference - Added multiple installation methods (go install, binary, source) - Moved TODO.md to docs/.internal/ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
363f12f4da
commit
654f8df1ad
14 changed files with 1387 additions and 37 deletions
|
|
@ -28,7 +28,7 @@ The `core` command provides a unified interface for Go/Wails development, multi-
|
|||
| Build for targets | `core build --targets linux/amd64,darwin/arm64` | Cross-compile |
|
||||
| Build SDK | `core build sdk` | Generate API clients from OpenAPI |
|
||||
| Preview release | `core ci` | Dry-run publish (safe default) |
|
||||
| Publish release | `core ci --were-go-for-launch` | Actually publish artifacts |
|
||||
| Publish release | `core ci --we-are-go-for-launch` | Actually publish artifacts |
|
||||
| Check environment | `core doctor` | Verify tools installed |
|
||||
| Multi-repo status | `core dev health` | Quick summary across repos |
|
||||
| Multi-repo workflow | `core dev work` | Status + commit + push |
|
||||
|
|
@ -82,12 +82,12 @@ core build sdk
|
|||
core ci # Dry-run: shows what would be published
|
||||
|
||||
# Step 3: Actually publish (explicit flag required)
|
||||
core ci --were-go-for-launch # Actually publish to targets
|
||||
core ci --were-go-for-launch --draft # Publish as draft
|
||||
core ci --were-go-for-launch --prerelease # Publish as prerelease
|
||||
core ci --we-are-go-for-launch # Actually publish to targets
|
||||
core ci --we-are-go-for-launch --draft # Publish as draft
|
||||
core ci --we-are-go-for-launch --prerelease # Publish as prerelease
|
||||
```
|
||||
|
||||
**Why safe by default?** `core ci` always does a dry-run unless you explicitly say `--were-go-for-launch`.
|
||||
**Why safe by default?** `core ci` always does a dry-run unless you explicitly say `--we-are-go-for-launch`.
|
||||
|
||||
```bash
|
||||
# Release workflow utilities
|
||||
|
|
@ -562,7 +562,7 @@ Go project?
|
|||
└── Build: core build [--targets <os/arch>]
|
||||
└── Build SDK: core build sdk
|
||||
└── Preview publish: core ci
|
||||
└── Publish: core ci --were-go-for-launch
|
||||
└── Publish: core ci --we-are-go-for-launch
|
||||
|
||||
PHP/Laravel project?
|
||||
└── Start dev: core php dev [--https]
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
// - S3-compatible storage
|
||||
// - Custom endpoints
|
||||
//
|
||||
// Safe by default: runs in dry-run mode unless --were-go-for-launch is specified.
|
||||
// Safe by default: runs in dry-run mode unless --we-are-go-for-launch is specified.
|
||||
// Configuration via .core/release.yaml.
|
||||
package ci
|
||||
|
||||
|
|
|
|||
|
|
@ -79,46 +79,46 @@ core dev impact core-php
|
|||
|
||||
```bash
|
||||
# List tasks
|
||||
core dev tasks
|
||||
core ai tasks
|
||||
|
||||
# Filter by status and priority
|
||||
core dev tasks --status pending --priority high
|
||||
core ai tasks --status pending --priority high
|
||||
|
||||
# Filter by labels
|
||||
core dev tasks --labels bug,urgent
|
||||
core ai tasks --labels bug,urgent
|
||||
|
||||
# Show task details
|
||||
core dev task abc123
|
||||
core ai task abc123
|
||||
|
||||
# Auto-select highest priority task
|
||||
core dev task --auto
|
||||
core ai task --auto
|
||||
|
||||
# Claim a task
|
||||
core dev task abc123 --claim
|
||||
core ai task abc123 --claim
|
||||
|
||||
# Update task status
|
||||
core dev task:update abc123 --status in_progress
|
||||
core ai task:update abc123 --status in_progress
|
||||
|
||||
# Add progress notes
|
||||
core dev task:update abc123 --progress 50 --notes 'Halfway done'
|
||||
core ai task:update abc123 --progress 50 --notes 'Halfway done'
|
||||
|
||||
# Complete a task
|
||||
core dev task:complete abc123 --output 'Feature implemented'
|
||||
core ai task:complete abc123 --output 'Feature implemented'
|
||||
|
||||
# Mark as failed
|
||||
core dev task:complete abc123 --failed --error 'Build failed'
|
||||
core ai task:complete abc123 --failed --error 'Build failed'
|
||||
|
||||
# Commit with task reference
|
||||
core dev task:commit abc123 -m 'add user authentication'
|
||||
core ai task:commit abc123 -m 'add user authentication'
|
||||
|
||||
# Commit with scope and push
|
||||
core dev task:commit abc123 -m 'fix login bug' --scope auth --push
|
||||
core ai task:commit abc123 -m 'fix login bug' --scope auth --push
|
||||
|
||||
# Create PR for task
|
||||
core dev task:pr abc123
|
||||
core ai task:pr abc123
|
||||
|
||||
# Create draft PR with labels
|
||||
core dev task:pr abc123 --draft --labels 'enhancement,needs-review'
|
||||
core ai task:pr abc123 --draft --labels 'enhancement,needs-review'
|
||||
```
|
||||
|
||||
## Service API Management
|
||||
|
|
|
|||
|
|
@ -283,7 +283,7 @@ core dev impact core-php
|
|||
|
||||
## Registry
|
||||
|
||||
These commands use `repos.yaml` to know which repos to manage. See [Configuration](example.md#registry) for format.
|
||||
These commands use `repos.yaml` to know which repos to manage. See [repos.yaml](../../../configuration.md#reposyaml) for format.
|
||||
|
||||
Use `core setup` to clone all repos from the registry.
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,9 @@ Unified interface for Go/PHP development, multi-repo management, and deployment.
|
|||
## Installation
|
||||
|
||||
```bash
|
||||
core go install
|
||||
go install github.com/host-uk/core/cmd/core@latest
|
||||
```
|
||||
|
||||
Verify: `core doctor`
|
||||
|
||||
See [Getting Started](../getting-started.md) for all installation options.
|
||||
|
|
|
|||
|
|
@ -191,16 +191,17 @@ Core looks for `repos.yaml` in:
|
|||
|
||||
```bash
|
||||
# Check workspace health
|
||||
core health
|
||||
core dev health
|
||||
|
||||
# Full workflow (status + commit + push)
|
||||
core work
|
||||
core dev work
|
||||
|
||||
# Build the project
|
||||
core build
|
||||
|
||||
# Run tests
|
||||
core test
|
||||
core go test # Go projects
|
||||
core php test # PHP projects
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -205,14 +205,148 @@ files:
|
|||
port: 8080
|
||||
```
|
||||
|
||||
## repos.yaml
|
||||
|
||||
Package registry for multi-repo workspaces:
|
||||
|
||||
```yaml
|
||||
# Organisation name (used for GitHub URLs)
|
||||
org: host-uk
|
||||
|
||||
# Base path for cloning (default: current directory)
|
||||
base_path: .
|
||||
|
||||
# Default settings for all repos
|
||||
defaults:
|
||||
ci: github
|
||||
license: EUPL-1.2
|
||||
branch: main
|
||||
|
||||
# Repository definitions
|
||||
repos:
|
||||
# Foundation packages (no dependencies)
|
||||
core-php:
|
||||
type: foundation
|
||||
description: Foundation framework
|
||||
|
||||
core-devops:
|
||||
type: foundation
|
||||
description: Development environment
|
||||
clone: false # Skip during setup (already exists)
|
||||
|
||||
# Module packages (depend on foundation)
|
||||
core-tenant:
|
||||
type: module
|
||||
depends_on: [core-php]
|
||||
description: Multi-tenancy module
|
||||
|
||||
core-admin:
|
||||
type: module
|
||||
depends_on: [core-php, core-tenant]
|
||||
description: Admin panel
|
||||
|
||||
core-api:
|
||||
type: module
|
||||
depends_on: [core-php]
|
||||
description: REST API framework
|
||||
|
||||
# Product packages (user-facing applications)
|
||||
core-bio:
|
||||
type: product
|
||||
depends_on: [core-php, core-tenant]
|
||||
description: Link-in-bio product
|
||||
domain: bio.host.uk.com
|
||||
|
||||
core-social:
|
||||
type: product
|
||||
depends_on: [core-php, core-tenant]
|
||||
description: Social scheduling
|
||||
domain: social.host.uk.com
|
||||
|
||||
# Templates
|
||||
core-template:
|
||||
type: template
|
||||
description: Starter template for new projects
|
||||
```
|
||||
|
||||
### repos.yaml Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `org` | Yes | GitHub organisation name |
|
||||
| `base_path` | No | Directory for cloning (default: `.`) |
|
||||
| `defaults` | No | Default settings applied to all repos |
|
||||
| `repos` | Yes | Map of repository definitions |
|
||||
|
||||
### Repository Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `type` | Yes | `foundation`, `module`, `product`, or `template` |
|
||||
| `description` | No | Human-readable description |
|
||||
| `depends_on` | No | List of package dependencies |
|
||||
| `clone` | No | Set `false` to skip during setup |
|
||||
| `domain` | No | Production domain (for products) |
|
||||
| `branch` | No | Override default branch |
|
||||
|
||||
### Package Types
|
||||
|
||||
| Type | Description | Dependencies |
|
||||
|------|-------------|--------------|
|
||||
| `foundation` | Core framework packages | None |
|
||||
| `module` | Reusable modules | Foundation packages |
|
||||
| `product` | User-facing applications | Foundation + modules |
|
||||
| `template` | Starter templates | Any |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Complete reference of environment variables used by Core CLI.
|
||||
|
||||
### Authentication
|
||||
|
||||
| Variable | Used By | Description |
|
||||
|----------|---------|-------------|
|
||||
| `GITHUB_TOKEN` | `core ci`, `core dev` | GitHub API authentication |
|
||||
| `ANTHROPIC_API_KEY` | `core ai`, `core dev claude` | Claude API key |
|
||||
| `AGENTIC_TOKEN` | `core ai task*` | Agentic API authentication |
|
||||
| `AGENTIC_BASE_URL` | `core ai task*` | Agentic API endpoint |
|
||||
|
||||
### Publishing
|
||||
|
||||
| Variable | Used By | Description |
|
||||
|----------|---------|-------------|
|
||||
| `NPM_TOKEN` | `core ci` (npm publisher) | npm registry auth token |
|
||||
| `CHOCOLATEY_API_KEY` | `core ci` (chocolatey publisher) | Chocolatey API key |
|
||||
| `DOCKER_USERNAME` | `core ci` (docker publisher) | Docker registry username |
|
||||
| `DOCKER_PASSWORD` | `core ci` (docker publisher) | Docker registry password |
|
||||
|
||||
### Deployment
|
||||
|
||||
| Variable | Used By | Description |
|
||||
|----------|---------|-------------|
|
||||
| `COOLIFY_URL` | `core php deploy` | Coolify server URL |
|
||||
| `COOLIFY_TOKEN` | `core php deploy` | Coolify API token |
|
||||
| `COOLIFY_APP_ID` | `core php deploy` | Production application ID |
|
||||
| `COOLIFY_STAGING_APP_ID` | `core php deploy --staging` | Staging application ID |
|
||||
|
||||
### Build
|
||||
|
||||
| Variable | Used By | Description |
|
||||
|----------|---------|-------------|
|
||||
| `CGO_ENABLED` | `core build`, `core go *` | Enable/disable CGO (default: 0) |
|
||||
| `GOOS` | `core build` | Target operating system |
|
||||
| `GOARCH` | `core build` | Target architecture |
|
||||
|
||||
### Configuration Paths
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `GITHUB_TOKEN` | GitHub authentication (via gh CLI) |
|
||||
| `NPM_TOKEN` | npm publish token |
|
||||
| `CHOCOLATEY_API_KEY` | Chocolatey publish key |
|
||||
| `COOLIFY_TOKEN` | Coolify deployment token |
|
||||
| `CORE_CONFIG` | Override config directory (default: `~/.core/`) |
|
||||
| `CORE_REGISTRY` | Override repos.yaml path |
|
||||
|
||||
---
|
||||
|
||||
## Defaults
|
||||
|
||||
|
|
|
|||
191
docs/getting-started.md
Normal file
191
docs/getting-started.md
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
# Getting Started
|
||||
|
||||
This guide walks you through installing Core and running your first build.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing Core, ensure you have:
|
||||
|
||||
| Tool | Minimum Version | Check Command |
|
||||
|------|-----------------|---------------|
|
||||
| Go | 1.23+ | `go version` |
|
||||
| Git | 2.30+ | `git --version` |
|
||||
|
||||
Optional (for specific features):
|
||||
|
||||
| Tool | Required For | Install |
|
||||
|------|--------------|---------|
|
||||
| `gh` | GitHub integration (`core dev issues`, `core dev reviews`) | [cli.github.com](https://cli.github.com) |
|
||||
| Docker | Container builds | [docker.com](https://docker.com) |
|
||||
| `task` | Task automation | `go install github.com/go-task/task/v3/cmd/task@latest` |
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Go Install (Recommended)
|
||||
|
||||
```bash
|
||||
# Install latest release
|
||||
go install github.com/host-uk/core/cmd/core@latest
|
||||
|
||||
# Verify installation
|
||||
core doctor
|
||||
```
|
||||
|
||||
If `core: command not found`, add Go's bin directory to your PATH:
|
||||
|
||||
```bash
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
```
|
||||
|
||||
### Option 2: Download Binary
|
||||
|
||||
Download pre-built binaries from [GitHub Releases](https://github.com/host-uk/core/releases):
|
||||
|
||||
```bash
|
||||
# macOS (Apple Silicon)
|
||||
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-darwin-arm64
|
||||
chmod +x core
|
||||
sudo mv core /usr/local/bin/
|
||||
|
||||
# macOS (Intel)
|
||||
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-darwin-amd64
|
||||
chmod +x core
|
||||
sudo mv core /usr/local/bin/
|
||||
|
||||
# Linux (x86_64)
|
||||
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-linux-amd64
|
||||
chmod +x core
|
||||
sudo mv core /usr/local/bin/
|
||||
```
|
||||
|
||||
### Option 3: Build from Source
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/host-uk/core.git
|
||||
cd core
|
||||
|
||||
# Build with Task (recommended)
|
||||
task cli:build
|
||||
# Binary at ./bin/core
|
||||
|
||||
# Or build with Go directly
|
||||
CGO_ENABLED=0 go build -o core ./cmd/core/
|
||||
sudo mv core /usr/local/bin/
|
||||
```
|
||||
|
||||
## Your First Build
|
||||
|
||||
### 1. Navigate to a Go Project
|
||||
|
||||
```bash
|
||||
cd ~/Code/my-go-project
|
||||
```
|
||||
|
||||
### 2. Initialise Configuration
|
||||
|
||||
```bash
|
||||
core setup
|
||||
```
|
||||
|
||||
This detects your project type and creates configuration files in `.core/`:
|
||||
- `build.yaml` - Build settings
|
||||
- `release.yaml` - Release configuration
|
||||
- `test.yaml` - Test commands
|
||||
|
||||
### 3. Build
|
||||
|
||||
```bash
|
||||
core build
|
||||
```
|
||||
|
||||
Output appears in `dist/`:
|
||||
|
||||
```
|
||||
dist/
|
||||
├── my-project-darwin-arm64.tar.gz
|
||||
├── my-project-linux-amd64.tar.gz
|
||||
└── CHECKSUMS.txt
|
||||
```
|
||||
|
||||
### 4. Cross-Compile (Optional)
|
||||
|
||||
```bash
|
||||
core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64
|
||||
```
|
||||
|
||||
## Your First Release
|
||||
|
||||
Releases are **safe by default** - Core runs in dry-run mode unless you explicitly confirm.
|
||||
|
||||
### 1. Preview
|
||||
|
||||
```bash
|
||||
core ci
|
||||
```
|
||||
|
||||
This shows what would be published without actually publishing.
|
||||
|
||||
### 2. Publish
|
||||
|
||||
```bash
|
||||
core ci --we-are-go-for-launch
|
||||
```
|
||||
|
||||
This creates a GitHub release with your built artifacts.
|
||||
|
||||
## Multi-Repo Workflow
|
||||
|
||||
If you work with multiple repositories (like the host-uk ecosystem):
|
||||
|
||||
### 1. Clone All Repositories
|
||||
|
||||
```bash
|
||||
mkdir host-uk && cd host-uk
|
||||
core setup
|
||||
```
|
||||
|
||||
Select packages in the interactive wizard.
|
||||
|
||||
### 2. Check Status
|
||||
|
||||
```bash
|
||||
core dev health
|
||||
# Output: "18 repos │ clean │ synced"
|
||||
```
|
||||
|
||||
### 3. Work Across Repos
|
||||
|
||||
```bash
|
||||
core dev work --status # See status table
|
||||
core dev work # Commit and push all dirty repos
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
| Task | Command | Documentation |
|
||||
|------|---------|---------------|
|
||||
| Run tests | `core go test` | [go/test](cmd/go/test/) |
|
||||
| Format code | `core go fmt --fix` | [go/fmt](cmd/go/fmt/) |
|
||||
| Lint code | `core go lint` | [go/lint](cmd/go/lint/) |
|
||||
| PHP development | `core php dev` | [php](cmd/php/) |
|
||||
| View all commands | `core --help` | [cmd](cmd/) |
|
||||
|
||||
## Getting Help
|
||||
|
||||
```bash
|
||||
# Check environment
|
||||
core doctor
|
||||
|
||||
# Command help
|
||||
core <command> --help
|
||||
|
||||
# Full documentation
|
||||
https://github.com/host-uk/core/tree/main/docs
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Configuration](configuration.md) - All config options
|
||||
- [Workflows](workflows.md) - Common task sequences
|
||||
- [Troubleshooting](troubleshooting.md) - When things go wrong
|
||||
112
docs/glossary.md
Normal file
112
docs/glossary.md
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
# Glossary
|
||||
|
||||
Definitions of terms used throughout Core CLI documentation.
|
||||
|
||||
## A
|
||||
|
||||
### Artifact
|
||||
A file produced by a build, typically a binary, archive, or checksum file. Artifacts are stored in the `dist/` directory and published during releases.
|
||||
|
||||
## C
|
||||
|
||||
### CGO
|
||||
Go's mechanism for calling C code. Core disables CGO by default (`CGO_ENABLED=0`) to produce statically-linked binaries that don't depend on system libraries.
|
||||
|
||||
### Changelog
|
||||
Automatically generated list of changes between releases, created from conventional commit messages. Configure in `.core/release.yaml`.
|
||||
|
||||
### Conventional Commits
|
||||
A commit message format: `type(scope): description`. Types include `feat`, `fix`, `docs`, `chore`. Core uses this to generate changelogs.
|
||||
|
||||
## D
|
||||
|
||||
### Dry-run
|
||||
A mode where commands show what they would do without actually doing it. `core ci` runs in dry-run mode by default for safety.
|
||||
|
||||
## F
|
||||
|
||||
### Foundation Package
|
||||
A core package with no dependencies on other packages. Examples: `core-php`, `core-devops`. These form the base of the dependency tree.
|
||||
|
||||
### FrankenPHP
|
||||
A modern PHP application server used by `core php dev`. Combines PHP with Caddy for high-performance serving.
|
||||
|
||||
## G
|
||||
|
||||
### `gh`
|
||||
The GitHub CLI tool. Required for commands that interact with GitHub: `core dev issues`, `core dev reviews`, `core dev ci`.
|
||||
|
||||
## L
|
||||
|
||||
### LinuxKit
|
||||
A toolkit for building lightweight, immutable Linux distributions. Core can build LinuxKit images via `core build --type linuxkit`.
|
||||
|
||||
## M
|
||||
|
||||
### Module (Go)
|
||||
A collection of Go packages with a `go.mod` file. Core's Go commands operate on modules.
|
||||
|
||||
### Module (Package)
|
||||
A host-uk package that depends on foundation packages. Examples: `core-tenant`, `core-admin`. Compare with **Foundation Package** and **Product**.
|
||||
|
||||
## P
|
||||
|
||||
### Package
|
||||
An individual repository in the host-uk ecosystem. Packages are defined in `repos.yaml` and managed with `core pkg` commands.
|
||||
|
||||
### Package Index
|
||||
The `repos.yaml` file that lists all packages in a workspace. Contains metadata like dependencies, type, and description.
|
||||
|
||||
### Product
|
||||
A user-facing application package. Examples: `core-bio`, `core-social`. Products depend on foundation and module packages.
|
||||
|
||||
### Publisher
|
||||
A release target configured in `.core/release.yaml`. Types include `github`, `docker`, `npm`, `homebrew`, `linuxkit`.
|
||||
|
||||
## R
|
||||
|
||||
### Registry (Docker/npm)
|
||||
A remote repository for container images or npm packages. Core can publish to registries during releases.
|
||||
|
||||
### `repos.yaml`
|
||||
The package index file defining all repositories in a workspace. Used by multi-repo commands like `core dev work`.
|
||||
|
||||
## S
|
||||
|
||||
### SDK
|
||||
Software Development Kit. Core can generate API client SDKs from OpenAPI specs via `core build sdk`.
|
||||
|
||||
## T
|
||||
|
||||
### Target
|
||||
A build target specified as `os/arch`, e.g., `linux/amd64`, `darwin/arm64`. Use `--targets` flag to specify.
|
||||
|
||||
## W
|
||||
|
||||
### Wails
|
||||
A framework for building desktop applications with Go backends and web frontends. Core detects Wails projects and uses appropriate build commands.
|
||||
|
||||
### Workspace (Go)
|
||||
A Go 1.18+ feature for working with multiple modules simultaneously. Managed via `core go work` commands.
|
||||
|
||||
### Workspace (Multi-repo)
|
||||
A directory containing multiple packages from `repos.yaml`. Created via `core setup` and managed with `core dev` commands.
|
||||
|
||||
## Symbols
|
||||
|
||||
### `.core/`
|
||||
Directory containing project configuration files:
|
||||
- `build.yaml` - Build settings
|
||||
- `release.yaml` - Release targets
|
||||
- `test.yaml` - Test configuration
|
||||
- `linuxkit/` - LinuxKit templates
|
||||
|
||||
### `--we-are-go-for-launch`
|
||||
Flag to disable dry-run mode and actually publish a release. Named as a deliberate friction to prevent accidental releases.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Configuration](configuration.md) - Config file reference
|
||||
- [Getting Started](getting-started.md) - First-time setup
|
||||
|
|
@ -5,14 +5,18 @@ Core is a unified CLI for the host-uk ecosystem - build, release, and deploy Go,
|
|||
## Installation
|
||||
|
||||
```bash
|
||||
# From any Go project
|
||||
core go install github.com/host-uk/core/cmd/core
|
||||
|
||||
# Or standard go install
|
||||
# Via Go (recommended)
|
||||
go install github.com/host-uk/core/cmd/core@latest
|
||||
|
||||
# Or download binary from releases
|
||||
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-$(go env GOOS)-$(go env GOARCH)
|
||||
chmod +x core && sudo mv core /usr/local/bin/
|
||||
|
||||
# Verify
|
||||
core doctor
|
||||
```
|
||||
|
||||
Verify: `core doctor`
|
||||
See [Getting Started](getting-started.md) for all installation options including building from source.
|
||||
|
||||
## Command Reference
|
||||
|
||||
|
|
@ -47,7 +51,7 @@ core build --targets linux/amd64,darwin/arm64
|
|||
|
||||
# Release (dry-run by default)
|
||||
core ci # Preview release
|
||||
core ci --were-go-for-launch # Actually publish
|
||||
core ci --we-are-go-for-launch # Actually publish
|
||||
|
||||
# Multi-repo workflow
|
||||
core dev work # Status + commit + push
|
||||
|
|
@ -71,10 +75,17 @@ Core uses `.core/` directory for project configuration:
|
|||
|
||||
And `repos.yaml` in workspace root for multi-repo management.
|
||||
|
||||
## Guides
|
||||
|
||||
- [Getting Started](getting-started.md) - Installation and first steps
|
||||
- [Workflows](workflows.md) - Common task sequences
|
||||
- [Troubleshooting](troubleshooting.md) - When things go wrong
|
||||
- [Migration](migration.md) - Moving from legacy tools
|
||||
|
||||
## Reference
|
||||
|
||||
- [Configuration](configuration.md) - All config options
|
||||
- [Examples](examples/) - Sample configurations
|
||||
- [Glossary](glossary.md) - Term definitions
|
||||
|
||||
## Claude Code Skill
|
||||
|
||||
|
|
|
|||
233
docs/migration.md
Normal file
233
docs/migration.md
Normal file
|
|
@ -0,0 +1,233 @@
|
|||
# Migration Guide
|
||||
|
||||
Migrating from legacy scripts and tools to Core CLI.
|
||||
|
||||
## From push-all.sh
|
||||
|
||||
The `push-all.sh` script has been replaced by `core dev` commands.
|
||||
|
||||
| Legacy | Core CLI | Notes |
|
||||
|--------|----------|-------|
|
||||
| `./push-all.sh --status` | `core dev work --status` | Status table |
|
||||
| `./push-all.sh --commit` | `core dev commit` | Commit dirty repos |
|
||||
| `./push-all.sh` | `core dev work` | Full workflow |
|
||||
|
||||
### Quick Migration
|
||||
|
||||
```bash
|
||||
# Instead of
|
||||
./push-all.sh --status
|
||||
|
||||
# Use
|
||||
core dev work --status
|
||||
```
|
||||
|
||||
### New Features
|
||||
|
||||
Core CLI adds features not available in the legacy script:
|
||||
|
||||
```bash
|
||||
# Quick health summary
|
||||
core dev health
|
||||
# Output: "18 repos │ clean │ synced"
|
||||
|
||||
# Pull repos that are behind
|
||||
core dev pull
|
||||
|
||||
# GitHub integration
|
||||
core dev issues # List open issues
|
||||
core dev reviews # List PRs needing review
|
||||
core dev ci # Check CI status
|
||||
|
||||
# Dependency analysis
|
||||
core dev impact core-php # What depends on core-php?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## From Raw Go Commands
|
||||
|
||||
Core wraps Go commands with enhanced defaults and output.
|
||||
|
||||
| Raw Command | Core CLI | Benefits |
|
||||
|-------------|----------|----------|
|
||||
| `go test ./...` | `core go test` | Filters warnings, sets CGO_ENABLED=0 |
|
||||
| `go test -coverprofile=...` | `core go cov` | HTML reports, thresholds |
|
||||
| `gofmt -w .` | `core go fmt --fix` | Uses goimports if available |
|
||||
| `golangci-lint run` | `core go lint` | Consistent interface |
|
||||
| `go build` | `core build` | Cross-compile, sign, archive |
|
||||
|
||||
### Why Use Core?
|
||||
|
||||
```bash
|
||||
# Raw go test shows linker warnings on macOS
|
||||
go test ./...
|
||||
# ld: warning: -no_pie is deprecated...
|
||||
|
||||
# Core filters noise
|
||||
core go test
|
||||
# PASS (clean output)
|
||||
```
|
||||
|
||||
### Environment Setup
|
||||
|
||||
Core automatically sets:
|
||||
- `CGO_ENABLED=0` - Static binaries
|
||||
- `MACOSX_DEPLOYMENT_TARGET=26.0` - Suppress macOS warnings
|
||||
- Colour output for coverage reports
|
||||
|
||||
---
|
||||
|
||||
## From Raw PHP Commands
|
||||
|
||||
Core orchestrates Laravel development services.
|
||||
|
||||
| Raw Command | Core CLI | Benefits |
|
||||
|-------------|----------|----------|
|
||||
| `php artisan serve` | `core php dev` | Adds Vite, Horizon, Reverb, Redis |
|
||||
| `./vendor/bin/pest` | `core php test` | Auto-detects test runner |
|
||||
| `./vendor/bin/pint` | `core php fmt --fix` | Consistent interface |
|
||||
| Manual Coolify deploy | `core php deploy` | Tracked, scriptable |
|
||||
|
||||
### Development Server Comparison
|
||||
|
||||
```bash
|
||||
# Raw: Start each service manually
|
||||
php artisan serve &
|
||||
npm run dev &
|
||||
php artisan horizon &
|
||||
php artisan reverb:start &
|
||||
|
||||
# Core: One command
|
||||
core php dev
|
||||
# Starts all services, shows unified logs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## From goreleaser
|
||||
|
||||
Core's release system is simpler than goreleaser for host-uk projects.
|
||||
|
||||
| goreleaser | Core CLI |
|
||||
|------------|----------|
|
||||
| `.goreleaser.yaml` | `.core/release.yaml` |
|
||||
| `goreleaser release --snapshot` | `core ci` (dry-run) |
|
||||
| `goreleaser release` | `core ci --we-are-go-for-launch` |
|
||||
|
||||
### Configuration Migration
|
||||
|
||||
**goreleaser:**
|
||||
```yaml
|
||||
builds:
|
||||
- main: ./cmd/app
|
||||
goos: [linux, darwin, windows]
|
||||
goarch: [amd64, arm64]
|
||||
|
||||
archives:
|
||||
- format: tar.gz
|
||||
files: [LICENSE, README.md]
|
||||
|
||||
release:
|
||||
github:
|
||||
owner: host-uk
|
||||
name: app
|
||||
```
|
||||
|
||||
**Core:**
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
project:
|
||||
name: app
|
||||
repository: host-uk/app
|
||||
|
||||
targets:
|
||||
- os: linux
|
||||
arch: amd64
|
||||
- os: darwin
|
||||
arch: arm64
|
||||
|
||||
publishers:
|
||||
- type: github
|
||||
```
|
||||
|
||||
### Key Differences
|
||||
|
||||
1. **Separate build and release** - Core separates `core build` from `core ci`
|
||||
2. **Safe by default** - `core ci` is dry-run unless `--we-are-go-for-launch`
|
||||
3. **Simpler config** - Fewer options, sensible defaults
|
||||
|
||||
---
|
||||
|
||||
## From Manual Git Operations
|
||||
|
||||
Core automates multi-repo git workflows.
|
||||
|
||||
| Manual | Core CLI |
|
||||
|--------|----------|
|
||||
| `cd repo1 && git status && cd ../repo2 && ...` | `core dev work --status` |
|
||||
| Check each repo for uncommitted changes | `core dev health` |
|
||||
| Commit each repo individually | `core dev commit` |
|
||||
| Push each repo individually | `core dev push` |
|
||||
|
||||
### Example: Committing Across Repos
|
||||
|
||||
**Manual:**
|
||||
```bash
|
||||
cd core-php
|
||||
git add -A
|
||||
git commit -m "feat: add feature"
|
||||
cd ../core-tenant
|
||||
git add -A
|
||||
git commit -m "feat: use new feature"
|
||||
# ... repeat for each repo
|
||||
```
|
||||
|
||||
**Core:**
|
||||
```bash
|
||||
core dev commit
|
||||
# Interactive: reviews changes, suggests messages
|
||||
# Adds Co-Authored-By automatically
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deprecated Commands
|
||||
|
||||
These commands have been removed or renamed:
|
||||
|
||||
| Deprecated | Replacement | Version |
|
||||
|------------|-------------|---------|
|
||||
| `core sdk generate` | `core build sdk` | v0.5.0 |
|
||||
| `core dev task*` | `core ai task*` | v0.8.0 |
|
||||
| `core release` | `core ci` | v0.6.0 |
|
||||
|
||||
---
|
||||
|
||||
## Version Compatibility
|
||||
|
||||
| Core Version | Go Version | Breaking Changes |
|
||||
|--------------|------------|------------------|
|
||||
| v1.0.0+ | 1.23+ | Stable API |
|
||||
| v0.8.0 | 1.22+ | Task commands moved to `ai` |
|
||||
| v0.6.0 | 1.22+ | Release command renamed to `ci` |
|
||||
| v0.5.0 | 1.21+ | SDK generation moved to `build sdk` |
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during migration:
|
||||
|
||||
1. Check [Troubleshooting](troubleshooting.md)
|
||||
2. Run `core doctor` to verify setup
|
||||
3. Use `--help` on any command: `core dev work --help`
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Getting Started](getting-started.md) - Fresh installation
|
||||
- [Workflows](workflows.md) - Common task sequences
|
||||
- [Configuration](configuration.md) - Config file reference
|
||||
332
docs/troubleshooting.md
Normal file
332
docs/troubleshooting.md
Normal file
|
|
@ -0,0 +1,332 @@
|
|||
# Troubleshooting
|
||||
|
||||
Common issues and how to resolve them.
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### "command not found: core"
|
||||
|
||||
**Cause:** Go's bin directory is not in your PATH.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Add to ~/.bashrc or ~/.zshrc
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
|
||||
# Then reload
|
||||
source ~/.bashrc # or ~/.zshrc
|
||||
```
|
||||
|
||||
### "go: module github.com/host-uk/core: no matching versions"
|
||||
|
||||
**Cause:** Go module proxy hasn't cached the latest version yet.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Bypass proxy
|
||||
GOPROXY=direct go install github.com/host-uk/core/cmd/core@latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Issues
|
||||
|
||||
### "no Go files in..."
|
||||
|
||||
**Cause:** Core couldn't find a main package to build.
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. Check you're in the correct directory
|
||||
2. Ensure `.core/build.yaml` has the correct `main` path:
|
||||
|
||||
```yaml
|
||||
project:
|
||||
main: ./cmd/myapp # Path to main package
|
||||
```
|
||||
|
||||
### "CGO_ENABLED=1 but no C compiler"
|
||||
|
||||
**Cause:** Build requires CGO but no C compiler is available.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Option 1: Disable CGO (if not needed)
|
||||
core build # Core disables CGO by default
|
||||
|
||||
# Option 2: Install a C compiler
|
||||
# macOS
|
||||
xcode-select --install
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install build-essential
|
||||
|
||||
# Windows
|
||||
# Install MinGW or use WSL
|
||||
```
|
||||
|
||||
### Build succeeds but binary doesn't run
|
||||
|
||||
**Cause:** Built for wrong architecture.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Check what you built
|
||||
file dist/myapp-*
|
||||
|
||||
# Build for your current platform
|
||||
core build --targets $(go env GOOS)/$(go env GOARCH)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Release Issues
|
||||
|
||||
### "dry-run mode, use --we-are-go-for-launch to publish"
|
||||
|
||||
**This is expected behaviour.** Core runs in dry-run mode by default for safety.
|
||||
|
||||
**To actually publish:**
|
||||
|
||||
```bash
|
||||
core ci --we-are-go-for-launch
|
||||
```
|
||||
|
||||
### "failed to create release: 401 Unauthorized"
|
||||
|
||||
**Cause:** GitHub token missing or invalid.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Authenticate with GitHub CLI
|
||||
gh auth login
|
||||
|
||||
# Or set token directly
|
||||
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
|
||||
```
|
||||
|
||||
### "no artifacts found in dist/"
|
||||
|
||||
**Cause:** You need to build before releasing.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Build first
|
||||
core build
|
||||
|
||||
# Then release
|
||||
core ci --we-are-go-for-launch
|
||||
```
|
||||
|
||||
### "tag already exists"
|
||||
|
||||
**Cause:** Trying to release a version that's already been released.
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. Update version in your code/config
|
||||
2. Or delete the existing tag (if intentional):
|
||||
|
||||
```bash
|
||||
git tag -d v1.0.0
|
||||
git push origin :refs/tags/v1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Repo Issues
|
||||
|
||||
### "repos.yaml not found"
|
||||
|
||||
**Cause:** Core can't find the package registry.
|
||||
|
||||
**Fix:**
|
||||
|
||||
Core looks for `repos.yaml` in:
|
||||
1. Current directory
|
||||
2. Parent directories (walking up to root)
|
||||
3. `~/Code/host-uk/repos.yaml`
|
||||
4. `~/.config/core/repos.yaml`
|
||||
|
||||
Either:
|
||||
- Run commands from a directory with `repos.yaml`
|
||||
- Use `--registry /path/to/repos.yaml`
|
||||
- Run `core setup` to bootstrap a new workspace
|
||||
|
||||
### "failed to clone: Permission denied (publickey)"
|
||||
|
||||
**Cause:** SSH key not configured for GitHub.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Check SSH connection
|
||||
ssh -T git@github.com
|
||||
|
||||
# If that fails, add your key
|
||||
ssh-add ~/.ssh/id_ed25519
|
||||
|
||||
# Or configure SSH
|
||||
# See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
|
||||
```
|
||||
|
||||
### "repository not found" during setup
|
||||
|
||||
**Cause:** You don't have access to the repository, or it doesn't exist.
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. Check you're authenticated: `gh auth status`
|
||||
2. Verify the repo exists and you have access
|
||||
3. For private repos, ensure your token has `repo` scope
|
||||
|
||||
---
|
||||
|
||||
## GitHub Integration Issues
|
||||
|
||||
### "gh: command not found"
|
||||
|
||||
**Cause:** GitHub CLI not installed.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install gh
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install gh
|
||||
|
||||
# Windows
|
||||
winget install GitHub.cli
|
||||
|
||||
# Then authenticate
|
||||
gh auth login
|
||||
```
|
||||
|
||||
### "core dev issues" shows nothing
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. No open issues exist
|
||||
2. Not authenticated with GitHub
|
||||
3. Not in a directory with `repos.yaml`
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Check auth
|
||||
gh auth status
|
||||
|
||||
# Check you're in a workspace
|
||||
ls repos.yaml
|
||||
|
||||
# Show all issues including closed
|
||||
core dev issues --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PHP Issues
|
||||
|
||||
### "frankenphp: command not found"
|
||||
|
||||
**Cause:** FrankenPHP not installed.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install frankenphp
|
||||
|
||||
# Or use Docker
|
||||
core php dev --docker
|
||||
```
|
||||
|
||||
### "core php dev" exits immediately
|
||||
|
||||
**Cause:** Usually a port conflict or missing dependency.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Check if port 8000 is in use
|
||||
lsof -i :8000
|
||||
|
||||
# Try a different port
|
||||
core php dev --port 9000
|
||||
|
||||
# Check logs for errors
|
||||
core php logs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Commands are slow
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. Large number of repositories
|
||||
2. Network latency to GitHub
|
||||
3. Go module downloads
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# For multi-repo commands, use health for quick check
|
||||
core dev health # Fast summary
|
||||
|
||||
# Instead of
|
||||
core dev work --status # Full table (slower)
|
||||
|
||||
# Pre-download Go modules
|
||||
go mod download
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting More Help
|
||||
|
||||
### Enable Verbose Output
|
||||
|
||||
Most commands support `-v` or `--verbose`:
|
||||
|
||||
```bash
|
||||
core build -v
|
||||
core go test -v
|
||||
```
|
||||
|
||||
### Check Environment
|
||||
|
||||
```bash
|
||||
core doctor
|
||||
```
|
||||
|
||||
This verifies all required tools are installed and configured.
|
||||
|
||||
### Report Issues
|
||||
|
||||
If you've found a bug:
|
||||
|
||||
1. Check existing issues: https://github.com/host-uk/core/issues
|
||||
2. Create a new issue with:
|
||||
- Core version (`core --version`)
|
||||
- OS and architecture (`go env GOOS GOARCH`)
|
||||
- Command that failed
|
||||
- Full error output
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Getting Started](getting-started.md) - Installation and first steps
|
||||
- [Configuration](configuration.md) - Config file reference
|
||||
- [doctor](cmd/doctor/) - Environment verification
|
||||
334
docs/workflows.md
Normal file
334
docs/workflows.md
Normal file
|
|
@ -0,0 +1,334 @@
|
|||
# Workflows
|
||||
|
||||
Common end-to-end workflows for Core CLI.
|
||||
|
||||
## Go Project: Build and Release
|
||||
|
||||
Complete workflow from code to GitHub release.
|
||||
|
||||
```bash
|
||||
# 1. Run tests
|
||||
core go test
|
||||
|
||||
# 2. Check coverage
|
||||
core go cov --threshold 80
|
||||
|
||||
# 3. Format and lint
|
||||
core go fmt --fix
|
||||
core go lint
|
||||
|
||||
# 4. Build for all platforms
|
||||
core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64
|
||||
|
||||
# 5. Preview release (dry-run)
|
||||
core ci
|
||||
|
||||
# 6. Publish
|
||||
core ci --we-are-go-for-launch
|
||||
```
|
||||
|
||||
**Output structure:**
|
||||
|
||||
```
|
||||
dist/
|
||||
├── myapp-darwin-arm64.tar.gz
|
||||
├── myapp-linux-amd64.tar.gz
|
||||
├── myapp-linux-arm64.tar.gz
|
||||
├── myapp-windows-amd64.zip
|
||||
└── CHECKSUMS.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PHP Project: Development to Deployment
|
||||
|
||||
Local development through to production deployment.
|
||||
|
||||
```bash
|
||||
# 1. Start development environment
|
||||
core php dev
|
||||
|
||||
# 2. Run tests (in another terminal)
|
||||
core php test --parallel
|
||||
|
||||
# 3. Check code quality
|
||||
core php fmt --fix
|
||||
core php analyse
|
||||
|
||||
# 4. Deploy to staging
|
||||
core php deploy --staging --wait
|
||||
|
||||
# 5. Verify staging
|
||||
# (manual testing)
|
||||
|
||||
# 6. Deploy to production
|
||||
core php deploy --wait
|
||||
|
||||
# 7. Monitor
|
||||
core php deploy:status
|
||||
```
|
||||
|
||||
**Rollback if needed:**
|
||||
|
||||
```bash
|
||||
core php deploy:rollback
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Repo: Daily Workflow
|
||||
|
||||
Working across the host-uk monorepo.
|
||||
|
||||
### Morning: Sync Everything
|
||||
|
||||
```bash
|
||||
# Quick health check
|
||||
core dev health
|
||||
|
||||
# Pull all repos that are behind
|
||||
core dev pull --all
|
||||
|
||||
# Check for issues assigned to you
|
||||
core dev issues --assignee @me
|
||||
```
|
||||
|
||||
### During Development
|
||||
|
||||
```bash
|
||||
# Work on code...
|
||||
|
||||
# Check status across all repos
|
||||
core dev work --status
|
||||
|
||||
# Commit changes (Claude-assisted messages)
|
||||
core dev commit
|
||||
|
||||
# Push when ready
|
||||
core dev push
|
||||
```
|
||||
|
||||
### End of Day
|
||||
|
||||
```bash
|
||||
# Full workflow: status → commit → push
|
||||
core dev work
|
||||
|
||||
# Check CI status
|
||||
core dev ci
|
||||
|
||||
# Review any failed builds
|
||||
core dev ci --failed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New Developer: Environment Setup
|
||||
|
||||
First-time setup for a new team member.
|
||||
|
||||
```bash
|
||||
# 1. Verify prerequisites
|
||||
core doctor
|
||||
|
||||
# 2. Create workspace directory
|
||||
mkdir ~/Code/host-uk && cd ~/Code/host-uk
|
||||
|
||||
# 3. Bootstrap workspace (interactive)
|
||||
core setup
|
||||
|
||||
# 4. Select packages in wizard
|
||||
# Use arrow keys, space to select, enter to confirm
|
||||
|
||||
# 5. Verify setup
|
||||
core dev health
|
||||
|
||||
# 6. Start working
|
||||
core dev work --status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI Pipeline: Automated Build
|
||||
|
||||
Example GitHub Actions workflow.
|
||||
|
||||
```yaml
|
||||
# .github/workflows/release.yml
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: '1.23'
|
||||
|
||||
- name: Install Core
|
||||
run: go install github.com/host-uk/core/cmd/core@latest
|
||||
|
||||
- name: Build
|
||||
run: core build --ci
|
||||
|
||||
- name: Release
|
||||
run: core ci --we-are-go-for-launch
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SDK Generation: API Client Updates
|
||||
|
||||
Generate SDK clients when API changes.
|
||||
|
||||
```bash
|
||||
# 1. Validate OpenAPI spec
|
||||
core sdk validate
|
||||
|
||||
# 2. Check for breaking changes
|
||||
core sdk diff --base v1.0.0
|
||||
|
||||
# 3. Generate SDKs
|
||||
core build sdk
|
||||
|
||||
# 4. Review generated code
|
||||
git diff
|
||||
|
||||
# 5. Commit if satisfied
|
||||
git add -A && git commit -m "chore: regenerate SDK clients"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Update: Cross-Repo Change
|
||||
|
||||
When updating a shared package like `core-php`.
|
||||
|
||||
```bash
|
||||
# 1. Make changes in core-php
|
||||
cd ~/Code/host-uk/core-php
|
||||
# ... edit code ...
|
||||
|
||||
# 2. Run tests
|
||||
core go test # or core php test
|
||||
|
||||
# 3. Check what depends on core-php
|
||||
core dev impact core-php
|
||||
|
||||
# Output:
|
||||
# core-tenant (direct)
|
||||
# core-admin (via core-tenant)
|
||||
# core-api (direct)
|
||||
# ...
|
||||
|
||||
# 4. Commit core-php changes
|
||||
core dev commit
|
||||
|
||||
# 5. Update dependent packages
|
||||
cd ~/Code/host-uk
|
||||
for pkg in core-tenant core-admin core-api; do
|
||||
cd $pkg
|
||||
composer update host-uk/core-php
|
||||
core php test
|
||||
cd ..
|
||||
done
|
||||
|
||||
# 6. Commit all updates
|
||||
core dev work
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hotfix: Emergency Production Fix
|
||||
|
||||
Fast path for critical fixes.
|
||||
|
||||
```bash
|
||||
# 1. Create hotfix branch
|
||||
git checkout -b hotfix/critical-bug main
|
||||
|
||||
# 2. Make fix
|
||||
# ... edit code ...
|
||||
|
||||
# 3. Test
|
||||
core go test --run TestCriticalPath
|
||||
|
||||
# 4. Build
|
||||
core build
|
||||
|
||||
# 5. Preview release
|
||||
core ci --prerelease
|
||||
|
||||
# 6. Publish hotfix
|
||||
core ci --we-are-go-for-launch --prerelease
|
||||
|
||||
# 7. Merge back to main
|
||||
git checkout main
|
||||
git merge hotfix/critical-bug
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation: Sync Across Repos
|
||||
|
||||
Keep documentation synchronised.
|
||||
|
||||
```bash
|
||||
# 1. List all docs
|
||||
core docs list
|
||||
|
||||
# 2. Sync to central location
|
||||
core docs sync --output ./docs-site
|
||||
|
||||
# 3. Review changes
|
||||
git diff docs-site/
|
||||
|
||||
# 4. Commit
|
||||
git add docs-site/
|
||||
git commit -m "docs: sync from packages"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting: Failed Build
|
||||
|
||||
When a build fails.
|
||||
|
||||
```bash
|
||||
# 1. Check environment
|
||||
core doctor
|
||||
|
||||
# 2. Clean previous artifacts
|
||||
rm -rf dist/
|
||||
|
||||
# 3. Verbose build
|
||||
core build -v
|
||||
|
||||
# 4. If Go-specific issues
|
||||
core go mod tidy
|
||||
core go mod verify
|
||||
|
||||
# 5. Check for test failures
|
||||
core go test -v
|
||||
|
||||
# 6. Review configuration
|
||||
cat .core/build.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Getting Started](getting-started.md) - First-time setup
|
||||
- [Troubleshooting](troubleshooting.md) - When things go wrong
|
||||
- [Configuration](configuration.md) - Config file reference
|
||||
Loading…
Add table
Reference in a new issue