mirror of
https://github.com/open-gitagent/langship.sh.git
synced 2026-08-03 07:21:04 +02:00
104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
# Contributing to Langship
|
|
|
|
Thanks for your interest. This guide covers the dev setup, what to run
|
|
before opening a PR, and the conventions we follow.
|
|
|
|
By contributing, you agree your contributions are licensed under the
|
|
[Apache License 2.0](./LICENSE) (the project's license). No CLA or DCO
|
|
sign-off is required.
|
|
|
|
## Code of conduct
|
|
|
|
Participation is governed by [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
|
|
Report concerns to <khush@lyzr.ai>.
|
|
|
|
## Repo layout
|
|
|
|
| Path | What |
|
|
|---|---|
|
|
| `cmd/flow/` | the `flow` server binary (API + Restate worker entry point) |
|
|
| `pkg/api/` | REST + SSE handlers |
|
|
| `pkg/orchestrator/`, `pkg/engine/` | DAG walk, execution context, events |
|
|
| `pkg/executors/` | node implementations (Build, Push, SAST, Approval, Promote, Deploy, …) |
|
|
| `pkg/awsdeploy/` | AWS Bedrock AgentCore adapter (STS, ECR, IAM, control-plane SigV4) |
|
|
| `pkg/storage/` | Mongo-backed stores (pipelines, runs, agents, credentials, environments) |
|
|
| `pkg/secrets/` | AES-GCM seal/open keyed off `FLOW_SECRET_KEY` |
|
|
| `web/` | Next.js UI (static export) |
|
|
| `langship-cli/` | the `langship` Python CLI |
|
|
|
|
## Dev environment
|
|
|
|
Backing services (Mongo, Restate, BuildKit, MinIO, registry) come up via
|
|
docker-compose; the Go API runs on the host. See the **Quickstart** and
|
|
**Dev (hot reload)** sections in the [README](./README.md) for the exact
|
|
commands. In short:
|
|
|
|
```bash
|
|
make services # docker-compose: mongo, restate, buildkitd, registry, minio
|
|
make watch # Go API with air (rebuilds on .go change) — or `make serve` for a stable binary
|
|
cd web && pnpm dev # Next dev server, /api proxies to :8090
|
|
```
|
|
|
|
Set `FLOW_SECRET_KEY` in your environment before working on anything that
|
|
touches credentials/environments — the API refuses credential writes
|
|
without it.
|
|
|
|
CLI:
|
|
|
|
```bash
|
|
pip install -e ./langship-cli
|
|
langship login --api-url http://localhost:8090
|
|
```
|
|
|
|
## Before you open a PR
|
|
|
|
- **Go**: `go build ./...` and `go test ./...` must pass. Run
|
|
`gofmt`/`go vet` on changed files.
|
|
- **Web**: `cd web && pnpm tsc --noEmit` must pass (and `pnpm build` if you
|
|
changed anything that affects the static export).
|
|
- **CLI**: `pip install -e ./langship-cli && langship --help` should work;
|
|
smoke-test any command you touched against a local server.
|
|
- Keep changes focused — one logical change per PR.
|
|
- Update the README / CLI README / `aude.md` if you changed behavior they
|
|
describe.
|
|
|
|
## Conventions
|
|
|
|
- **Commits**: imperative subject, ≤ ~72 chars (`feat:`/`fix:`/`refactor:`
|
|
prefixes are welcome but not required). Squash noise before pushing.
|
|
- **Branches**: `main` is the trunk; branch off it. Don't push directly to
|
|
`main` — open a PR.
|
|
- **Code style**: match the surrounding code. Comments explain *why*, not
|
|
*what*. Executors emit `__<node>` summary objects on output items;
|
|
follow that pattern.
|
|
- **Errors**: wrap with context (`fmt.Errorf("deploy: %w", err)`); the API
|
|
layer maps `storage.ErrNotFound` → 404 and `storage.ErrAlreadyExists` →
|
|
409.
|
|
- **No secrets in code or commits.** Anything sensitive goes through
|
|
`pkg/secrets` and is never returned by the API.
|
|
|
|
## Adding a node executor
|
|
|
|
1. Implement `executors.NodeExecutor` in `pkg/executors/<name>.go`. Read
|
|
the trigger payload via `firstItem(inputs)` for `agentId` /
|
|
`environment` / `fromBranch`. Emit each input item with a `__<name>`
|
|
summary attached.
|
|
2. Register it in `pkg/executors/registry.go` (pass any stores it needs
|
|
via `RegistryDeps`).
|
|
3. Add a catalog entry in `web/lib/node-catalog.ts` and a `<Name>Form` in
|
|
`web/components/canvas/node-form.tsx`.
|
|
4. If it pauses (like Approval), special-case it in
|
|
`pkg/orchestrator/walk.go` so it isn't wrapped in `restate.Run` (it
|
|
calls Restate context methods directly).
|
|
|
|
## Reporting bugs
|
|
|
|
Open a GitHub issue with: what you did, what you expected, what happened,
|
|
and the relevant logs (`flow` server output + the run's node logs from
|
|
`langship runs logs <id>` or `/api/executions/{id}/logs/{node}`).
|
|
|
|
## Security
|
|
|
|
Vulnerabilities go to <khush@lyzr.ai> privately — see
|
|
[SECURITY.md](./SECURITY.md). Do not open a public issue.
|