Skip to content

Commit e95c562

Browse files
Copilotoalders
Copilot
and
oalders
committed
Onboarding for Copilot
Co-authored-by: oalders <96205+oalders@users.noreply.github.com>
1 parent 8ced20b commit e95c562

File tree

4 files changed

+562
-1
lines changed

4 files changed

+562
-1
lines changed

‎DEVELOPMENT.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Development Setup Guide
2+
3+
This guide helps you set up a local development environment for MetaCPAN Web.
4+
5+
## Quick Setup
6+
7+
For automated setup, run:
8+
9+
```bash
10+
./bin/setup-dev
11+
```
12+
13+
This script will:
14+
- Check system requirements
15+
- Install system dependencies (libcmark-dev)
16+
- Install Perl development tools (carton, cpm)
17+
- Install all project dependencies
18+
- Build static assets
19+
- Set up git hooks
20+
- Run basic tests
21+
22+
## Manual Setup
23+
24+
If you prefer to set up manually or the automated script doesn't work in your environment:
25+
26+
### Prerequisites
27+
28+
- Perl 5.36+ (tested with 5.38.2)
29+
- Node.js 20+ (tested with 20.19.4)
30+
- npm 10+ (tested with 10.8.2)
31+
- System dependencies: libcmark-dev (on Ubuntu/Debian)
32+
33+
### Install Dependencies
34+
35+
1. **Install system dependencies:**
36+
```bash
37+
# On Ubuntu/Debian
38+
sudo apt-get install libcmark-dev
39+
40+
# On macOS
41+
brew install cmark
42+
```
43+
44+
2. **Install Perl tools:**
45+
```bash
46+
# Install carton and cpm
47+
cpan App::carton App::cpm
48+
```
49+
50+
3. **Install Node.js dependencies:**
51+
```bash
52+
npm install
53+
```
54+
55+
4. **Install Perl dependencies:**
56+
```bash
57+
# Using cpm (faster)
58+
cpm install --resolver=snapshot
59+
60+
# Or using carton
61+
carton install
62+
```
63+
64+
5. **Build static assets:**
65+
```bash
66+
npm run build
67+
```
68+
69+
6. **Set up git hooks:**
70+
```bash
71+
./git/setup.sh
72+
```
73+
74+
## Running the Application
75+
76+
### Development Server
77+
78+
```bash
79+
carton exec plackup -p 5001 -r app.psgi
80+
```
81+
82+
The application will be available at http://localhost:5001
83+
84+
### Alternative Servers
85+
86+
For better performance during development:
87+
88+
```bash
89+
# Using Gazelle
90+
carton exec plackup -p 5001 -s Gazelle -r app.psgi
91+
92+
# Using Starman
93+
carton exec plackup -p 5001 -s Starman app.psgi
94+
```
95+
96+
## Testing
97+
98+
### Run All Tests
99+
100+
```bash
101+
carton exec prove -l -r --jobs 2 t
102+
```
103+
104+
### Run Specific Tests
105+
106+
```bash
107+
# Basic functionality tests (work offline)
108+
carton exec prove -l t/moose.t t/assets.t t/session.t
109+
110+
# Specific controller tests
111+
carton exec prove -l t/controller/about.t
112+
```
113+
114+
### Note on Test Failures
115+
116+
Many tests require network access to `api.metacpan.org` and will fail in isolated environments. This is expected behavior. The core functionality tests (like `t/moose.t`, `t/assets.t`, etc.) should pass.
117+
118+
## Asset Development
119+
120+
### Building Assets
121+
122+
```bash
123+
# One-time build
124+
npm run build
125+
126+
# Minified build (for production)
127+
npm run build:min
128+
129+
# Watch for changes during development
130+
npm run build:watch
131+
```
132+
133+
### Asset Files
134+
135+
- Source files: `root/static/`
136+
- Built files: `root/assets/`
137+
- Build configuration: `build-assets.mjs`
138+
139+
## Code Quality
140+
141+
### Linting
142+
143+
The project uses `precious` to orchestrate various linters:
144+
145+
```bash
146+
# Install precious (if not using Docker)
147+
./bin/install-precious /usr/local/bin
148+
149+
# Lint all files
150+
precious lint --all
151+
152+
# Lint specific files
153+
precious lint path/to/file
154+
155+
# Auto-fix issues
156+
precious tidy --all
157+
```
158+
159+
### Git Hooks
160+
161+
Pre-commit hooks are configured to run `precious` automatically. Set them up with:
162+
163+
```bash
164+
./git/setup.sh
165+
```
166+
167+
## Docker Development
168+
169+
For a completely isolated environment, use Docker:
170+
171+
```bash
172+
# Build development image
173+
docker build --target develop -t metacpan-web:dev .
174+
175+
# Run development container
176+
docker run -it -p 5001:8000 -v $(pwd):/app metacpan-web:dev
177+
```
178+
179+
## Configuration
180+
181+
### Local Configuration
182+
183+
Create a `metacpan_web_local.yaml` file to override settings:
184+
185+
```yaml
186+
api: http://127.0.0.1:5000 # Local API server
187+
debug: 1
188+
```
189+
190+
### Environment Variables
191+
192+
- `PLACK_ENV`: Set to `development` for development mode
193+
- `METACPAN_WEB_HOME`: Path to application root (auto-detected)
194+
195+
## Troubleshooting
196+
197+
### Common Issues
198+
199+
1. **Asset map errors**: Run `npm run build` to generate assets
200+
2. **Permission errors**: Check that `local/` directory is writable
201+
3. **Test failures**: Most network-dependent tests will fail without API access
202+
4. **Module not found**: Ensure `carton exec` is used or local lib is in `PERL5LIB`
203+
204+
### Getting Help
205+
206+
- Check the main [README.md](README.md)
207+
- Review existing [issues](https://github.com/metacpan/metacpan-web/issues)
208+
- Ask in the MetaCPAN IRC channel or discussions

‎README.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,30 @@ We strongly recommend using
2121
[metacpan-docker](https://github.com/metacpan/metacpan-docker). This will give
2222
you a virtual machine already configured and ready to start developing on.
2323

24-
If you prefer not to use Docker, the following commands will get you started:
24+
If you prefer not to use Docker, you can set up a local development environment:
25+
26+
## Quick Setup
27+
28+
For automated setup, run:
29+
30+
```bash
31+
./bin/setup-dev
32+
```
33+
34+
This will install all dependencies, build assets, and verify your setup.
2535

2636
## Installing Manually
2737

38+
If you prefer manual setup or need more control:
39+
2840
```bash
2941
carton install
3042
npm install
3143
export PATH="$(realpath ./node_modules/.bin):$PATH"
3244
```
3345

46+
For detailed setup instructions, see [DEVELOPMENT.md](DEVELOPMENT.md).
47+
3448
### Building Static Assets
3549

3650
```bash

‎bin/setup-dev‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
#!/bin/bash
2+
3+
# MetaCPAN Web Development Environment Setup Script
4+
# This script automates the setup process for new developers
5+
6+
set -euo pipefail
7+
8+
# Colors for output
9+
RED='\033[0;31m'
10+
GREEN='\033[0;32m'
11+
YELLOW='\033[1;33m'
12+
NC='\033[0m' # No Color
13+
14+
log_info() {
15+
echo -e "${GREEN}[INFO]${NC} $1"
16+
}
17+
18+
log_warn() {
19+
echo -e "${YELLOW}[WARN]${NC} $1"
20+
}
21+
22+
log_error() {
23+
echo -e "${RED}[ERROR]${NC} $1"
24+
}
25+
26+
# Check if we're in the right directory
27+
if [[ ! -f "cpanfile" || ! -f "package.json" ]]; then
28+
log_error "This script must be run from the metacpan-web repository root directory"
29+
exit 1
30+
fi
31+
32+
log_info "Setting up MetaCPAN Web development environment..."
33+
34+
# Check system requirements
35+
log_info "Checking system requirements..."
36+
37+
# Check Perl
38+
if ! command -v perl >/dev/null 2>&1; then
39+
log_error "Perl is required but not installed"
40+
exit 1
41+
fi
42+
PERL_VERSION=$(perl -e 'print $^V' | sed 's/v//')
43+
log_info "Found Perl $PERL_VERSION"
44+
45+
# Check Node.js
46+
if ! command -v node >/dev/null 2>&1; then
47+
log_error "Node.js is required but not installed"
48+
exit 1
49+
fi
50+
NODE_VERSION=$(node --version)
51+
log_info "Found Node.js $NODE_VERSION"
52+
53+
# Check npm
54+
if ! command -v npm >/dev/null 2>&1; then
55+
log_error "npm is required but not installed"
56+
exit 1
57+
fi
58+
NPM_VERSION=$(npm --version)
59+
log_info "Found npm $NPM_VERSION"
60+
61+
# Install system dependencies
62+
log_info "Installing system dependencies..."
63+
if command -v apt-get >/dev/null 2>&1; then
64+
if ! dpkg -l | grep -q libcmark-dev; then
65+
log_info "Installing libcmark-dev..."
66+
sudo apt-get update -qq
67+
sudo apt-get install -y libcmark-dev
68+
else
69+
log_info "libcmark-dev already installed"
70+
fi
71+
else
72+
log_warn "apt-get not found, please install libcmark development package manually"
73+
fi
74+
75+
# Install Perl development tools
76+
log_info "Installing Perl development tools..."
77+
78+
# Check if carton is available
79+
if ! command -v carton >/dev/null 2>&1; then
80+
log_info "Installing Carton..."
81+
cpanm Carton
82+
else
83+
log_info "Carton already installed"
84+
fi
85+
86+
# Check if cpm is available
87+
if ! command -v cpm >/dev/null 2>&1; then
88+
log_info "Installing App::cpm..."
89+
cpanm App::cpm
90+
else
91+
log_info "App::cpm already installed"
92+
fi
93+
94+
# Add local Perl lib to PATH if needed
95+
if [[ -d "$HOME/perl5/bin" ]]; then
96+
export PERL5LIB="$HOME/perl5/lib/perl5:${PERL5LIB:-}"
97+
export PATH="$HOME/perl5/bin:$PATH"
98+
fi
99+
100+
# Install npm dependencies
101+
log_info "Installing Node.js dependencies..."
102+
npm install
103+
104+
# Install Perl dependencies
105+
log_info "Installing Perl dependencies..."
106+
if command -v cpm >/dev/null 2>&1; then
107+
log_info "Using cpm for faster installation..."
108+
cpm install --resolver=snapshot
109+
else
110+
log_info "Using carton..."
111+
carton install
112+
fi
113+
114+
# Build static assets
115+
log_info "Building static assets..."
116+
npm run build
117+
118+
# Set up git hooks
119+
if [[ -f "git/setup.sh" ]]; then
120+
log_info "Setting up git hooks..."
121+
./git/setup.sh
122+
else
123+
log_warn "git/setup.sh not found, skipping git hooks setup"
124+
fi
125+
126+
# Run basic tests to verify setup
127+
log_info "Running basic tests to verify setup..."
128+
if command -v carton >/dev/null 2>&1; then
129+
log_info "Testing with offline-capable tests..."
130+
if carton exec prove -l t/moose.t t/assets.t t/static-files.t t/session.t; then
131+
log_info "Basic tests passed!"
132+
else
133+
log_warn "Some basic tests failed, but the setup might still be functional"
134+
fi
135+
else
136+
log_warn "Carton not available, skipping tests"
137+
fi
138+
139+
log_info "Development environment setup complete!"
140+
echo
141+
log_info "You can now:"
142+
echo " • Run the development server: carton exec plackup -p 5001 -r app.psgi"
143+
echo " • Run tests: carton exec prove -l -r t"
144+
echo " • Build assets: npm run build"
145+
echo " • Watch for asset changes: npm run build:watch"
146+
echo
147+
log_warn "Note: Some tests require network access to api.metacpan.org and will fail in isolated environments"

0 commit comments

Comments
 (0)