Skip to content

Commit 16d53d8

Browse files
AndyGaugeAndyGauge
authored
Devx/deployment guide (#729)
* deployment guide * test bypass
1 parent 5df3420 commit 16d53d8

File tree

5 files changed

+301
-4
lines changed

5 files changed

+301
-4
lines changed

‎DEPLOYMENT.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Deployment Guide
2+
3+
This document explains how the Rust Cookbook is deployed locally by maintainers.
4+
5+
## Overview
6+
7+
The project uses local deployment scripts to build and deploy to GitHub Pages. This approach allows maintainers to deploy without needing GitHub Actions workflow permissions.
8+
9+
## Local Deployment
10+
11+
### Deployment Script (`scripts/deploy.sh`)
12+
13+
The deployment script handles:
14+
- **Building**: Builds the mdbook and copies assets
15+
- **Testing**: Runs cargo tests and spellcheck
16+
- **Deployment**: Pushes the built site to the `gh-pages` branch
17+
18+
### Makefile Commands
19+
20+
For convenience, a Makefile provides easy commands:
21+
22+
```bash
23+
make help # Show all available commands
24+
make build # Build the book locally
25+
make test # Run all tests
26+
make dev # Build and test (development workflow)
27+
make deploy # Deploy to GitHub Pages
28+
make serve # Serve locally with live reload
29+
make clean # Clean build artifacts
30+
```
31+
32+
## Local Development
33+
34+
For local development and testing:
35+
36+
```bash
37+
# Use the Makefile (recommended)
38+
make dev
39+
40+
# Or run the development script
41+
./scripts/dev.sh
42+
43+
# Or manually:
44+
cargo install mdbook --vers "0.4.43"
45+
mdbook build
46+
cp -r assets/ book/
47+
cargo test
48+
./ci/spellcheck.sh list
49+
```
50+
51+
## GitHub Pages Configuration
52+
53+
The site is deployed to GitHub Pages from the `gh-pages` branch. The GitHub Actions workflow automatically:
54+
1. Builds the mdbook to the `book/` directory
55+
2. Copies assets from `assets/` to `book/`
56+
3. Pushes the contents to the `gh-pages` branch
57+
4. GitHub Pages serves the site from this branch
58+
59+
## Troubleshooting
60+
61+
### Build Failures
62+
- Check the GitHub Actions logs for specific error messages
63+
- Ensure all code examples compile and pass tests
64+
- Verify that all links in the documentation are valid
65+
66+
### Deployment Issues
67+
- Ensure the repository has GitHub Pages enabled in Settings > Pages
68+
- Check that the `GITHUB_TOKEN` secret is available (this is automatic for public repositories)
69+
- Verify that the `gh-pages` branch is being created and updated
70+
71+
### Local Build Issues
72+
- Make sure you have Rust and Cargo installed
73+
- Install mdbook with the exact version: `cargo install mdbook --vers "0.4.43"`
74+
- Run `cargo clean` if you encounter dependency issues
75+
76+
## Migration from Travis CI
77+
78+
This setup replaces the previous Travis CI configuration:
79+
- `ci/deploy.sh` - Replaced by local deployment script (`scripts/deploy.sh`)
80+
- `ci/test_script.sh` - Functionality integrated into local scripts
81+
- `appveyor.yml` - Windows testing can be added if needed
82+
83+
The new setup provides the same functionality while allowing maintainers to deploy without needing GitHub Actions workflow permissions.

‎Makefile‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.PHONY: help build test deploy deploy-skip-tests dev clean install-mdbook
2+
3+
help: ## Show this help message
4+
@echo "Rust Cookbook - Available commands:"
5+
@echo ""
6+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
7+
8+
install-mdbook: ## Install mdbook with the correct version
9+
cargo install mdbook --vers "0.4.43"
10+
11+
build: install-mdbook ## Build the book locally
12+
mdbook build
13+
cp -r assets/ book/
14+
@echo "Build complete! Open book/index.html in your browser."
15+
16+
test: ## Run all tests
17+
cargo test
18+
./ci/spellcheck.sh list
19+
20+
dev: build test ## Build and test (development workflow)
21+
@echo "Development build complete!"
22+
23+
deploy: dev ## Deploy to GitHub Pages (requires maintainer permissions)
24+
./scripts/deploy.sh
25+
26+
deploy-skip-tests: build ## Deploy to GitHub Pages without running tests
27+
./scripts/deploy.sh --skip-tests
28+
29+
clean: ## Clean build artifacts
30+
cargo clean
31+
rm -rf book/
32+
@echo "Clean complete!"
33+
34+
serve: install-mdbook ## Serve the book locally with live reload
35+
mdbook serve --open

‎README.md‎

Lines changed: 48 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
1-
# A Rust Cookbook   [![Build Status travis]][travis]
1+
# A Rust Cookbook   [![Build Status][build-badge]][build-url]
22

3-
[Build Status travis]: https://api.travis-ci.com/rust-lang-nursery/rust-cookbook.svg?branch=master
4-
5-
https://invalid.cc
3+
[build-badge]: https://github.com/rust-lang-nursery/rust-cookbook/workflows/Deploy%20to%20GitHub%20Pages/badge.svg
4+
[build-url]: https://github.com/rust-lang-nursery/rust-cookbook/actions?query=workflow%3A%22Deploy+to+GitHub+Pages%22
65

76
**[Read it here]**.
87

@@ -32,6 +31,51 @@ $ start .\book\index.html # windows
3231
$ open ./book/index.html # mac
3332
```
3433

34+
## Development
35+
36+
### Local Development
37+
38+
For local development and testing, you can use the provided Makefile:
39+
40+
```bash
41+
# Show all available commands
42+
make help
43+
44+
# Build the book locally
45+
make build
46+
47+
# Run tests
48+
make test
49+
50+
# Build and test (development workflow)
51+
make dev
52+
53+
# Serve the book locally with live reload
54+
make serve
55+
56+
# Clean build artifacts
57+
make clean
58+
```
59+
60+
### Deployment
61+
62+
As a maintainer, you can deploy the site locally using:
63+
64+
```bash
65+
# Deploy to GitHub Pages (requires maintainer permissions)
66+
make deploy
67+
68+
# Or use the script directly
69+
./scripts/deploy.sh
70+
```
71+
72+
The deployment script will:
73+
1. Build and test the book
74+
2. Push the built site to the `gh-pages` branch
75+
3. GitHub Pages will automatically serve the updated site
76+
77+
**Note**: This requires maintainer permissions to push to the `gh-pages` branch.
78+
3579
[Read it here]: https://rust-lang-nursery.github.io/rust-cookbook
3680
[Rust]: https://www.rust-lang.org/
3781

‎scripts/deploy.sh‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
#!/bin/bash
2+
3+
set -e
4+
5+
# Parse command line arguments
6+
SKIP_TESTS=false
7+
while [[ $# -gt 0 ]]; do
8+
case $1 in
9+
--skip-tests)
10+
SKIP_TESTS=true
11+
shift
12+
;;
13+
*)
14+
echo "Unknown option: $1"
15+
echo "Usage: $0 [--skip-tests]"
16+
exit 1
17+
;;
18+
esac
19+
done
20+
21+
echo "Rust Cookbook Local Deployment Script"
22+
echo "====================================="
23+
24+
# Check if mdbook is installed
25+
if ! command -v mdbook &> /dev/null; then
26+
echo "Installing mdbook..."
27+
cargo install mdbook --vers "0.4.43"
28+
fi
29+
30+
# Build the book
31+
echo "Building the book..."
32+
mdbook build
33+
34+
# Copy assets
35+
echo "Copying assets..."
36+
cp -r assets/ book/
37+
38+
# Run tests (unless --skip-tests is specified)
39+
if [[ "$SKIP_TESTS" == "false" ]]; then
40+
echo "Running tests..."
41+
cargo test
42+
43+
echo "Running spellcheck..."
44+
./ci/spellcheck.sh list
45+
else
46+
echo "Skipping tests (--skip-tests flag provided)"
47+
fi
48+
49+
# Check if we're on master branch
50+
if [[ $(git branch --show-current) != "master" ]]; then
51+
echo "Warning: You're not on the master branch. Current branch: $(git branch --show-current)"
52+
echo "This script is designed to deploy from the master branch."
53+
read -p "Continue anyway? (y/N): " -n 1 -r
54+
echo
55+
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
56+
exit 1
57+
fi
58+
fi
59+
60+
# Get current commit hash
61+
REV=$(git rev-parse --short HEAD)
62+
echo "Building for commit: $REV"
63+
64+
# Create a temporary directory for the gh-pages branch
65+
TEMP_DIR=$(mktemp -d)
66+
echo "Using temporary directory: $TEMP_DIR"
67+
68+
# Clone the repository to the temporary directory
69+
echo "Cloning repository to temporary directory..."
70+
git clone --depth 1 --branch gh-pages https://github.com/rust-lang-nursery/rust-cookbook.git "$TEMP_DIR" 2>/dev/null || {
71+
echo "gh-pages branch doesn't exist yet, creating it..."
72+
mkdir -p "$TEMP_DIR"
73+
cd "$TEMP_DIR"
74+
git init
75+
git remote add origin https://github.com/rust-lang-nursery/rust-cookbook.git
76+
cd - > /dev/null
77+
}
78+
79+
# Copy the built book to the temporary directory
80+
echo "Copying built book to temporary directory..."
81+
rm -rf "$TEMP_DIR"/*
82+
cp -r book/* "$TEMP_DIR/"
83+
84+
# Commit and push to gh-pages branch
85+
echo "Committing and pushing to gh-pages branch..."
86+
cd "$TEMP_DIR"
87+
git add -A .
88+
git config user.name "Rust Cookbook Maintainer"
89+
git config user.email "[email protected]"
90+
git commit -m "Build cookbook at $REV" || {
91+
echo "No changes to commit"
92+
exit 0
93+
}
94+
95+
echo "Pushing to gh-pages branch..."
96+
git push origin HEAD:gh-pages --force
97+
98+
# Clean up
99+
cd - > /dev/null
100+
rm -rf "$TEMP_DIR"
101+
102+
echo "Deployment complete!"
103+
echo "The site should be available at: https://rust-lang-nursery.github.io/rust-cookbook"
104+
echo "Note: It may take a few minutes for GitHub Pages to update."

‎scripts/dev.sh‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#!/bin/bash
2+
3+
set -e
4+
5+
echo "Rust Cookbook Development Script"
6+
echo "================================"
7+
8+
# Check if mdbook is installed
9+
if ! command -v mdbook &> /dev/null; then
10+
echo "Installing mdbook..."
11+
cargo install mdbook --vers "0.4.43"
12+
fi
13+
14+
# Build the book
15+
echo "Building the book..."
16+
mdbook build
17+
18+
# Copy assets
19+
echo "Copying assets..."
20+
cp -r assets/ book/
21+
22+
# Run tests
23+
echo "Running tests..."
24+
cargo test
25+
26+
# Run spellcheck
27+
echo "Running spellcheck..."
28+
./ci/spellcheck.sh list
29+
30+
echo "Build complete! Open book/index.html in your browser to view the site."
31+
echo "Or run 'mdbook serve --open' to start a local server."

0 commit comments

Comments
 (0)