Skip to main content

🤝 Contributing

💻 Development Workflow​

📋 Prerequisites​

  • Go 1.26+ — required for compilation
  • Node.js 20+ — required for building the documentation site

🔨 Building​

End users: Use the setup script instead — see Installation. The go build workflow below is for development and testing only.

# Compile the binary
go build -o tresor.exe .

# Build with version info
go build -ldflags "-X main.version=1.0.0 -X main.commit=abc123" -o tresor.exe .

🧪 Running Tests​

# All unit tests
go test ./...

# Single package
go test ./internal/engine/...

# E2E integration (requires running daemon)
./tresor.exe run --config config.yaml &
go test -tags=integration ./e2e/...

See the /Tresor-docs/docs/dev/testing page for the full verification sequence.

📝 Code Style​

  • Follow Go conventions (gofmt for formatting, govet for static analysis)
  • Match existing code patterns: naming, comment density, error handling
  • Use table-driven tests for comprehensive coverage
  • Write tests before or alongside implementation

🔌 Adding a New Plugin​

  1. Create a new file in internal/plugins/ (e.g., my_plugin.go)
  2. Implement one or more transformer interfaces (RequestTransformer, ResponseTransformer, StreamResponseTransformer)
  3. Register the plugin in an init() function: Register("my_plugin", &MyPlugin{})
  4. Add a config schema for web UI consumption
  5. Write unit tests covering request transform, response transform, and streaming (if applicable)
  6. Run go test ./internal/plugins/... to verify

See the /Tresor-docs/docs/dev/plugin-system page for interface definitions and examples.

🌐 Modifying the Web UI​

The web UI source files are in internal/api/web/:

  • index.html — Page structure and tab content (downstreams, aliases, rules, plugins, settings, about)
  • style.css — Styling and responsive layout
  • app.js — Application logic, API calls, dynamic rendering, login screen, theme toggle

The embedded files are compiled into the binary via //go:embed web/* in internal/api/embed.go. After editing, rebuild the binary.

🧪 Testing Web UI Changes​

  1. Rebuild: go build -o tresor.exe .
  2. Start the daemon: ./tresor.exe run --config config.yaml
  3. Navigate to each affected tab in the browser
  4. Perform core interactions (create, edit, delete, hot-switch)
  5. Verify the UI reflects expected state and no JavaScript errors occur

📚 Documentation​

The documentation site is a standalone Docusaurus project (repo: ladbaby/Tresor-docs). Docs source files are in docs-content/, organized under user/ and dev/ subdirectories.

# Install dependencies (first time only)
npm install

# Start development server with hot reload
npm start

# Build for production
npm run build

# Serve the built site locally
npm run serve

✏️ Documentation Conventions​

  • Use .mdx format for all documentation pages
  • Frontmatter must include title and description
  • Use <Tabs> and <TabItem> for platform-specific instructions
  • Link between related pages using absolute paths with the full site path (e.g., /Tresor-docs/docs/user/configuration/basics)
  • Keep user docs focused on what and why; keep developer docs focused on how

📬 Pull Request Process​

  1. Fork the repository and create a feature branch
  2. Make your changes following the code style guidelines
  3. Run the full test suite: go test ./...
  4. Update documentation if your change affects user-facing behavior
  5. Submit the pull request with a clear description of changes
  6. Ensure CI checks pass (build, tests)

📌 Git Conventions​

  • Commit messages follow conventional commit style: type(scope): message
    • Types: feat, fix, docs, ci, refactor, test
    • Example: fix(engine): handle nil pipeline context in streaming transform
  • Keep commits focused and atomic
  • Squash related commits before merging