Contributing¶

We love contributions! Here's how to help make opencode_initializer better.

Code of Conduct¶

This project follows the Contributor Covenant 2.1. Please read it before contributing.

Reporting Bugs¶

Check existing issues
Use the bug report template
Include: OS, shell version, installer version, full error output

Feature Requests¶

Check existing issues
Use the feature request template
Describe: problem, proposed solution, alternatives considered

Pull Requests¶

Setup¶

git clone https://github.com/AlexanderNarbaev/opencode_initializer.git
cd opencode_initializer

Development Workflow¶

Create a branch: git checkout -b feat/my-feature
Make changes: Edit shell scripts, tests, docs
Test: Run the test suite
Lint: Run ShellCheck and shfmt
Commit: Follow Conventional Commits
Push: git push origin feat/my-feature
PR: Create a pull request on GitHub

Code Style¶

Rule	Example
2-space indent	`local var="value"`
snake_case variables	`my_variable`, `SCRIPT_DIR` for globals
`[[ ]]` over `[ ]`	`if [[ -f "$file" ]]; then`
`$(cmd)` over backticks	`result=$(command)`
`local` for all function vars	`local name="$1"`
Quoted variables	`"$HOME"`, not `$HOME`
No hardcoded secrets	Use CLI args or env vars
`set -euo pipefail`	At top of every script
`set -o inherit_errexit`	In setup.sh

Testing¶

# Full test suite
bash tests/run_tests.sh

# Syntax check only
bash -n setup.sh
for f in src/lib/*.sh src/modes/*.sh; do bash -n "$f"; done

# ShellCheck
shellcheck setup.sh src/lib/*.sh src/modes/*.sh

# Format check
shfmt -d -i 2 -ci setup.sh src/lib/*.sh src/modes/*.sh

Pre-commit Hooks¶

Install pre-commit for automatic checks:

pip install pre-commit
pre-commit install

This runs ShellCheck, shfmt, and gitleaks on every commit.

Documentation¶

Documentation is built with MkDocs Material:

# Activate venv
source .venv-docs/bin/activate

# Serve locally
mkdocs serve

# Build
mkdocs build

# Deploy (maintainers only)
mkdocs gh-deploy

PR Checklist¶

Code follows style guide (2-space indent, snake_case)
No hardcoded secrets
New features have tests
bash -n passes on all modified files
bash tests/run_tests.sh passes
AGENTS.md updated if architecture changes
Commit messages follow conventional format

Security¶

Never commit secrets. Use CLI args or environment variables.
Report vulnerabilities privately: see SECURITY.md
gitleaks pre-commit hook catches common secret patterns

Project Structure¶

opencode_initializer/
├── setup.sh              # Orchestrator (561 lines)
├── dev.sh                # CLI tool
├── opencode.json         # AI config
├── mkdocs.yml            # Docs config
├── src/
│   ├── lib/              # 38 modules
│   └── modes/            # 5 mode scripts
├── tests/                # Test suites
├── docs/                 # Documentation (this site)
├── migrations/           # Database migrations
├── scripts/              # Utility scripts
├── .github/              # CI + templates
└── AGENTS.md             # AI agent instructions

Recognition¶

Contributors are recognized in the GitHub contributors graph and release notes.

Thank you for contributing!

See also: - Architecture — system design and module layout - Reference — CLI and config schema - Getting Started — installation and first use