mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-11-07 08:55:37 +08:00
167 lines
4.0 KiB
Markdown
167 lines
4.0 KiB
Markdown
# Contributing to Navigator
|
|
|
|
## Prerequisites
|
|
|
|
Install [mise](https://mise.jdx.dev/). This is used to setup the development environment.
|
|
|
|
```bash
|
|
# Install mise (macOS/Linux)
|
|
curl https://mise.run | sh
|
|
```
|
|
|
|
After installing `mise` be sure to activate the environment by running `mise activate` or [add it to your shell](https://mise.jdx.dev/getting-started.html).
|
|
|
|
Project uses Rust 1.88+ and Python 3.12+.
|
|
|
|
## Getting started
|
|
|
|
```bash
|
|
# Install dependencies and build
|
|
mise install
|
|
|
|
# Build the project
|
|
mise build
|
|
|
|
# Run all project tests
|
|
mise test
|
|
|
|
# Run the cluster agent
|
|
mise run server
|
|
|
|
# Run the CLI, this will build/run the cli from source
|
|
nav --help
|
|
|
|
# Run the sandbox
|
|
mise run sandbox
|
|
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
crates/
|
|
├── navigator-core/ # Core library
|
|
├── navigator-server/ # Main gateway server, ingress for all operations
|
|
├── navigator-sandbox/ # Sandbox execution environment
|
|
└── navigator-cli/ # Command-line interface
|
|
python/ # Python bindings
|
|
proto/ # Protocol buffer definitions
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Building
|
|
|
|
```bash
|
|
mise run build # Debug build
|
|
mise run build:release # Release build
|
|
mise run check # Quick compile check
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
mise run test # All tests (Rust + Python)
|
|
mise run test:rust # Rust tests only
|
|
mise run test:python # Python tests only
|
|
```
|
|
|
|
### Linting & Formatting
|
|
|
|
```bash
|
|
# Rust
|
|
mise run fmt # Format code
|
|
mise run fmt:check # Check formatting
|
|
mise run clippy # Run Clippy lints
|
|
|
|
# Python
|
|
mise run python:fmt # Format with ruff
|
|
mise run python:lint # Lint with ruff
|
|
mise run python:typecheck # Type check with ty
|
|
```
|
|
|
|
### Running Components
|
|
|
|
```bash
|
|
mise run server # Start the server
|
|
mise run cli -- --help # Run CLI with arguments
|
|
mise run sandbox # Run sandbox
|
|
```
|
|
|
|
### Git Hooks (Pre-commit)
|
|
|
|
We use `mise generate git-pre-commit` for local pre-commit checks.
|
|
|
|
Generate a Git pre-commit hook that runs the `pre-commit` task:
|
|
|
|
```bash
|
|
mise generate git-pre-commit --write --task=pre-commit
|
|
```
|
|
|
|
### Kubernetes Development
|
|
|
|
The project uses [k3d](https://k3d.io/) for local Kubernetes development. All required tools (k3d, kubectl, skaffold, helm) are managed by mise.
|
|
|
|
```bash
|
|
mise run kube:start # Create/start k3d cluster with local registry
|
|
mise run kube:stop # Stop cluster (preserves state)
|
|
mise run kube:destroy # Delete cluster completely
|
|
|
|
mise run kube:deploy # Build and deploy via skaffold
|
|
mise run kube:dev # Dev mode with hot reload
|
|
mise run test:e2e:sandbox # Run sandbox e2e tests via skaffold verify
|
|
```
|
|
|
|
The cluster exposes port 8080 for the server and includes a local registry at `localhost:5000`.
|
|
|
|
The sandbox E2E task uses a Skaffold profile (`e2e-sandbox`) that loads images directly into the
|
|
k3d cluster instead of pushing to a registry.
|
|
|
|
## Code Style
|
|
|
|
- **Rust**: Formatted with `rustfmt`, linted with Clippy (pedantic + nursery)
|
|
- **Python**: Formatted and linted with `ruff`, type-checked with `mypy --strict`
|
|
|
|
Run `mise run all` before committing to check everything.
|
|
|
|
## Commit Messages
|
|
|
|
This project uses [Conventional Commits](https://www.conventionalcommits.org/). All commit messages must follow the format:
|
|
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
**Types:**
|
|
|
|
- `feat` - New feature
|
|
- `fix` - Bug fix
|
|
- `docs` - Documentation only
|
|
- `chore` - Maintenance tasks (dependencies, build config)
|
|
- `refactor` - Code change that neither fixes a bug nor adds a feature
|
|
- `test` - Adding or updating tests
|
|
- `ci` - CI/CD changes
|
|
- `perf` - Performance improvements
|
|
|
|
**Examples:**
|
|
|
|
```
|
|
feat(cli): add --verbose flag to nav run
|
|
fix(sandbox): handle timeout errors gracefully
|
|
docs: update installation instructions
|
|
chore(deps): bump tokio to 1.40
|
|
```
|
|
|
|
## Pull Requests
|
|
|
|
1. Create a feature branch from `main`
|
|
2. Make your changes with tests
|
|
3. Run `mise run all` to verify
|
|
4. Open a PR with a clear description
|
|
|
|
Use the `create-gitlab-mr` skill to help with opening your pull request.
|