Skip to content

Commit 5310593

Browse files
apiadapiad
committed
docs: add updating documentation and update deploy guide
1 parent 2763990 commit 5310593

File tree

3 files changed

+345
-0
lines changed

3 files changed

+345
-0
lines changed

‎docs/deploy.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,87 @@
22

33
Getting the **Gemini CLI Opinionated Framework** up and running is an automated, interactive process. Whether you're starting a new project or integrating into an existing one, the `install.sh` script is your primary tool.
44

5+
## Installation Modes
6+
7+
The framework supports two installation modes with different trade-offs:
8+
9+
### Copy Mode (Default)
10+
11+
The framework is downloaded and extracted without git tracking.
12+
13+
**Characteristics:**
14+
- Framework files are a standalone copy
15+
- No `.git/` directory in `.opencode/`
16+
- Updates via re-running installer
17+
- Each project has its own copy
18+
19+
**Trade-offs:**
20+
- Pros:
21+
- Simple, no git knowledge required
22+
- Projects are independent
23+
- No risk of accidentally modifying framework files
24+
- Cons:
25+
- Cannot rollback using git history
26+
- Must manually track framework updates
27+
- Cannot contribute to framework development
28+
29+
**Best for:**
30+
- Projects that need stability
31+
- Users unfamiliar with git submodules
32+
- Production environments
33+
34+
### Link Mode (Submodule)
35+
36+
The framework is installed as a git submodule.
37+
38+
**Characteristics:**
39+
- Framework is a git submodule linked to `opencode-core`
40+
- Maintains `.git/` connection
41+
- Updates via `git pull` or submodule commands
42+
- Shares framework across projects
43+
44+
**Trade-offs:**
45+
- Pros:
46+
- Easy updates via `git submodule update`
47+
- Can rollback using git history
48+
- Can contribute changes back to framework
49+
- Cons:
50+
- More complex git workflow
51+
- Requires understanding of submodules
52+
- Framework changes affect all projects
53+
54+
**Best for:**
55+
- Framework development
56+
- Active development requiring latest features
57+
- Users comfortable with git submodules
58+
59+
### When to Use Each Mode
60+
61+
| Scenario | Recommended Mode |
62+
|----------|------------------|
63+
| Production project, stability needed | Copy |
64+
| Experimental project | Link |
65+
| Contributing to framework | Link |
66+
| New to git | Copy |
67+
| Multiple projects sharing updates | Link |
68+
| Isolated project | Copy |
69+
70+
### Switching Modes
71+
72+
To switch modes, run the installer with the desired mode:
73+
74+
```bash
75+
# Copy to Link
76+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=link
77+
78+
# Link to Copy
79+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=copy
80+
```
81+
82+
The installer will prompt for confirmation when switching modes.
83+
84+
---
85+
586
## 🚀 The Unified Installer
687

788
The fastest way to install or update the framework is to run the following command:

‎docs/updating.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Updating the Framework
2+
3+
This guide explains how to keep your OpenCode framework installation up to date, switch between installation modes, and troubleshoot common issues.
4+
5+
---
6+
7+
## Updating the Framework
8+
9+
### Copy Mode
10+
11+
In copy mode, the framework is downloaded and extracted without git tracking. To update:
12+
13+
```bash
14+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash
15+
```
16+
17+
The installer will:
18+
1. Detect the existing `.opencode/` directory
19+
2. Clone the latest version from the repository
20+
3. Preserve your protected files (`opencode.json`, `.opencode/style-guide.md`)
21+
4. Show you what will be updated before proceeding
22+
23+
To update to a specific version:
24+
25+
```bash
26+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --version v2.0.0
27+
```
28+
29+
### Link Mode (Submodule)
30+
31+
In link mode, the framework is installed as a git submodule. To update:
32+
33+
```bash
34+
cd .opencode && git fetch && git checkout vX.Y.Z
35+
```
36+
37+
Or use the installer to update the submodule:
38+
39+
```bash
40+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=link --update
41+
```
42+
43+
---
44+
45+
## Switching Between Modes
46+
47+
### Copy → Link
48+
49+
Run the installer with `--mode=link`:
50+
51+
```bash
52+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=link
53+
```
54+
55+
> **Warning:** This will convert your installation to a git submodule. The installer will prompt for confirmation.
56+
57+
### Link → Copy
58+
59+
Run the installer with `--mode=copy`:
60+
61+
```bash
62+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=copy
63+
```
64+
65+
> **Warning:** This will remove the `.git/` directory from the framework, breaking the submodule connection. Your customizations will be preserved.
66+
67+
---
68+
69+
## Updating opencode-core
70+
71+
### For Link Mode
72+
73+
The framework repository (`opencode-core`) is tracked as a submodule. To update to a specific version:
74+
75+
```bash
76+
cd .opencode
77+
git fetch origin
78+
git checkout v2.0.0
79+
cd ..
80+
git add .opencode
81+
git commit -m "chore: update opencode-core to v2.0.0"
82+
```
83+
84+
To switch back to the latest from a branch:
85+
86+
```bash
87+
cd .opencode
88+
git checkout main
89+
```
90+
91+
### For Copy Mode
92+
93+
Simply re-run the installer. It will download the latest version and preserve your configurations.
94+
95+
---
96+
97+
## Troubleshooting
98+
99+
### Updates Break Things
100+
101+
If an update causes issues:
102+
103+
1. **Check the changelog** - Review `.opencode/CHANGELOG.md` for breaking changes
104+
2. **Run diagnostics**:
105+
```bash
106+
make doctor
107+
```
108+
3. **Check for dependency updates**:
109+
```bash
110+
make install-deps
111+
```
112+
113+
### Rolling Back
114+
115+
#### Copy Mode Rollback
116+
117+
Since copy mode doesn't track git history, you cannot rollback automatically. To restore a previous state:
118+
119+
1. Identify the version you need from the installer changelog
120+
2. Reinstall that specific version:
121+
```bash
122+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --version v1.9.0
123+
```
124+
125+
#### Link Mode Rollback
126+
127+
Git submodules preserve history. To rollback:
128+
129+
```bash
130+
cd .opencode
131+
git log --oneline # Find the previous commit
132+
git checkout v1.9.0 # Rollback to previous version
133+
cd ..
134+
git add .opencode
135+
git commit -m "chore: rollback opencode-core to v1.9.0"
136+
```
137+
138+
To find available versions:
139+
140+
```bash
141+
cd .opencode
142+
git tag -l # List all available versions
143+
```
144+
145+
### Stuck in Broken State
146+
147+
If your installation is corrupted:
148+
149+
1. **Remove the framework directory:**
150+
```bash
151+
rm -rf .opencode
152+
```
153+
154+
2. **Reinstall:**
155+
```bash
156+
curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=copy
157+
```
158+
159+
3. **Restore your configurations** from backups (if available in `~/.opencode/`)
160+
161+
---
162+
163+
## Getting Help
164+
165+
- **Documentation:** See other files in `/docs/`
166+
- **Issues:** Report bugs at https://github.com/apiad/opencode/issues
167+
- **Framework Repo:** https://github.com/apiad/opencode-core
168+
169+
---
170+
171+
*See [deploy.md](deploy.md) for information about installation modes and when to use each.*

‎tests/test_phase5_docs.sh‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
#!/usr/bin/env bash
2+
# Test script for Phase 5: Documentation and Testing
3+
# Verifies all completion criteria for Phase 5
4+
5+
set -e
6+
7+
REPO_DIR="/home/apiad/Projects/personal/opencode"
8+
9+
echo "=== Phase 5: Documentation and Testing Test ==="
10+
11+
# Check 1: README.md updated with new installation instructions
12+
echo -n "Checking README.md has installation instructions... "
13+
if ! grep -q "curl.*install.sh.*bash" "$REPO_DIR/README.md"; then
14+
echo "FAIL: Installation command not in README.md"
15+
exit 1
16+
fi
17+
echo "OK"
18+
19+
# Check 2: README.md mentions both installation modes
20+
echo -n "Checking README.md mentions both modes... "
21+
if ! grep -qE "(--mode=copy|--mode=link|copy mode|link mode)" "$REPO_DIR/README.md"; then
22+
echo "FAIL: Installation modes not documented"
23+
exit 1
24+
fi
25+
echo "OK"
26+
27+
# Check 3: README.md references opencode-core
28+
echo -n "Checking README.md references opencode-core... "
29+
if ! grep -q "opencode-core" "$REPO_DIR/README.md"; then
30+
echo "FAIL: opencode-core not referenced"
31+
exit 1
32+
fi
33+
echo "OK"
34+
35+
# Check 4: docs/deploy.md exists and mentions modes
36+
echo -n "Checking docs/deploy.md... "
37+
if [[ ! -f "$REPO_DIR/docs/deploy.md" ]]; then
38+
echo "FAIL: docs/deploy.md not found"
39+
exit 1
40+
fi
41+
echo "OK"
42+
43+
# Check 5: docs/updating.md exists (new file for update instructions)
44+
echo -n "Checking docs/updating.md exists... "
45+
if [[ ! -f "$REPO_DIR/docs/updating.md" ]]; then
46+
echo "FAIL: docs/updating.md not found"
47+
exit 1
48+
fi
49+
echo "OK"
50+
51+
# Check 6: docs/updating.md mentions both modes
52+
echo -n "Checking docs/updating.md has mode instructions... "
53+
if ! grep -qE "copy|link|submodule" "$REPO_DIR/docs/updating.md"; then
54+
echo "FAIL: Update instructions incomplete"
55+
exit 1
56+
fi
57+
echo "OK"
58+
59+
# Check 7: install.sh is executable and has proper shebang
60+
echo -n "Checking install.sh shebang... "
61+
if ! head -1 "$REPO_DIR/install.sh" | grep -q "^#!/usr/bin/env bash"; then
62+
echo "FAIL: install.sh missing proper shebang"
63+
exit 1
64+
fi
65+
echo "OK"
66+
67+
# Check 8: install.sh has usage function
68+
echo -n "Checking install.sh has usage... "
69+
if ! grep -q -E "function usage|usage\(\)" "$REPO_DIR/install.sh"; then
70+
echo "FAIL: install.sh missing usage function"
71+
exit 1
72+
fi
73+
echo "OK"
74+
75+
# Check 9: Documentation links verified (docs exist)
76+
echo -n "Checking docs/ structure... "
77+
DOC_COUNT=$(ls -1 "$REPO_DIR/docs/"*.md 2>/dev/null | wc -l)
78+
if [[ "$DOC_COUNT" -lt 3 ]]; then
79+
echo "FAIL: Expected at least 3 docs, found $DOC_COUNT"
80+
exit 1
81+
fi
82+
echo "OK ($DOC_COUNT docs)"
83+
84+
# Check 10: templates/README.md is proper template
85+
echo -n "Checking templates/README.md is template... "
86+
if ! grep -q -i "project" "$REPO_DIR/templates/README.md"; then
87+
echo "FAIL: templates/README.md not a proper template"
88+
exit 1
89+
fi
90+
echo "OK"
91+
92+
echo ""
93+
echo "=== All Phase 5 checks passed ==="

0 commit comments

Comments
 (0)