CONTRIBUTING.md

Rama main · réplica de lectura del repositorio original.

# Contributing to Sablier

Thank you for your interest in contributing to Sablier! This guide will help you get started with contributing to the project.

## Table of Contents

- [Contributing to Sablier](#contributing-to-sablier)
  - [Table of Contents](#table-of-contents)
  - [Getting Started](#getting-started)
    - [Fork the Repository](#fork-the-repository)
    - [Clone Your Fork](#clone-your-fork)
    - [Create a Branch](#create-a-branch)
  - [Contribution Guidelines](#contribution-guidelines)
    - [Conventional Commits](#conventional-commits)
  - [Development Guide](#development-guide)
    - [Setup](#setup)
    - [Compiling](#compiling)
      - [Build the Binary](#build-the-binary)
      - [Build for Specific Platform](#build-for-specific-platform)
      - [Run Locally](#run-locally)
      - [Build Docker Image](#build-docker-image)
    - [Theme Development](#theme-development)
    - [Generated Files](#generated-files)
    - [Testing](#testing)
      - [Run All Tests](#run-all-tests)
      - [Run Linters](#run-linters)
    - [Running Long Tests (Testcontainers)](#running-long-tests-testcontainers)
      - [Running Testcontainer Tests](#running-testcontainer-tests)
      - [Skipping Long Tests](#skipping-long-tests)
      - [Tests That Need a LocalStack Token](#tests-that-need-a-localstack-token)
  - [Submitting Your Contribution](#submitting-your-contribution)
    - [Before Submitting](#before-submitting)
    - [Create a Pull Request](#create-a-pull-request)
    - [After Merge](#after-merge)
  - [Getting Help](#getting-help)
  - [Code of Conduct](#code-of-conduct)
  - [License](#license)

---

## Getting Started

### Fork the Repository

1. Navigate to the [Sablier repository](https://github.com/sablierapp/sablier)
2. Click the **Fork** button in the top-right corner
3. This creates a copy of the repository under your GitHub account

### Clone Your Fork

```bash
git clone https://github.com/YOUR_USERNAME/sablier.git
cd sablier
```

### Create a Branch

Create a new branch for your feature or bug fix:

```bash
git checkout -b my-new-feature
```

## Contribution Guidelines

### Conventional Commits

We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages. This leads to more readable messages and helps with automated versioning and changelog generation.

**Format:**
```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Types:**
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, missing semicolons, etc.)
- `refactor`: Code refactoring without changing functionality
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `build`: Changes to build system or dependencies
- `ci`: Changes to CI configuration
- `chore`: Other changes that don't modify src or test files

**Examples:**
```bash
git commit -m "feat(provider): add Podman support"
git commit -m "fix(api): resolve race condition in session management"
git commit -m "docs: update installation guide with new Docker image"
git commit -m "test(kubernetes): add integration tests for StatefulSets"
```

**Breaking Changes:**

For breaking changes, add `!` after the type or add `BREAKING CHANGE:` in the footer:

```bash
git commit -m "feat(api)!: remove deprecated /v1/start endpoint"

# or

git commit -m "feat(api): update authentication mechanism

BREAKING CHANGE: API now requires API key in header instead of query parameter"
```

---

## Development Guide

### Setup

Before building the project, use `mise` to prepare the development environment:

- Install `mise` (if not already installed): https://mise.jdx.dev/getting-started.html
- Run `mise install` in the project root to install all required tools from the project's `.tool-versions`/`mise` configuration.

### Compiling

#### Build the Binary

```bash
make build
```

This creates a binary in the current directory (e.g., `sablier_draft_linux-amd64`).

#### Build for Specific Platform

```bash
# Linux
GOOS=linux GOARCH=amd64 make build

# macOS
GOOS=darwin GOARCH=amd64 make build

# Windows
GOOS=windows GOARCH=amd64 make build
```

#### Run Locally

```bash
# Build and run
make build
./sablier start --help

# Or run directly
go run cmd/sablier/sablier.go start --provider.name=docker
```

#### Build Docker Image

```bash
make docker
```

---

### Theme Development

Themes are Go HTML templates that receive a [`TemplateData`](pkg/theme/types.go) value. A JSON Schema describing every available field is published alongside each release and served at:

```
https://sablierapp.dev/theme.schema.json
```

The schema is generated from the `TemplateData` and `Instance` Go types using `cmd/schemagen` and committed at [`docs/theme.schema.json`](docs/theme.schema.json).

#### Regenerating the schema

Whenever `TemplateData` or `Instance` in [`pkg/theme/types.go`](pkg/theme/types.go) changes, regenerate the schema:

```bash
make schema
# or via go generate:
go generate ./pkg/theme/...
```

#### Verifying the schema is up to date

```bash
make check-schema
```

This command fails with a clear message if the committed schema does not match the current Go types. It is intended for use in CI to catch forgotten regenerations.

---

### Generated Files

Several files under `docs/` are generated from Go source and committed to the repository. Regenerate them whenever their source changes, and commit the result.

| File | Generated from | Individual target |
|------|----------------|-------------------|
| `docs/content/reference/cli.md` | the CLI flags and config structs | `make cli-docs` |
| `docs/content/reference/labels.md` | the label doc comments in [`pkg/sablier/labels.go`](pkg/sablier/labels.go) | `make labels-docs` |
| `docs/content/how-to-guides/advanced/observability/metrics.md` | the Prometheus collectors in [`pkg/metrics`](pkg/metrics) | `make metrics-docs` |
| `docs/static/theme.schema.json` | the theme types in [`pkg/theme/types.go`](pkg/theme/types.go) | `make schema` |
| `docs/static/openapi.json` | the HTTP API definition | `make openapi` |

Regenerate all of them at once:

```bash
make generate
```

CI verifies that every generated file is up to date on each pull request:

```bash
make check-generate
```

`make check-generate` fails with a message naming the stale file if any generated file no longer matches its source. Run `make generate`, commit the changes, and the check passes.

---

### Testing

#### Run All Tests

```bash
make test
```

Or using Go directly:

```bash
go test ./...
```

#### Run Linters

```bash
make lint
```

---

### Running Long Tests (Testcontainers)

Some tests use [Testcontainers](https://golang.testcontainers.org/) to spin up real containers (Docker, Kubernetes, etc.). These tests are longer-running and require Docker to be installed and running.

#### Running Testcontainer Tests

By default, testcontainer tests are included in the regular test suite:

```bash
make test
```

#### Skipping Long Tests

If you want to skip testcontainer tests during development:

```bash
go test -short ./...
```

Mark long-running tests with:

```go
func TestMyLongRunningTest(t *testing.T) {
    if testing.Short() {
        t.Skip("Skipping long-running test")
    }
    // Test code...
}
```

#### Tests That Need a LocalStack Token

The AWS ECS integration test (`TestECSProvider_Integration` in `pkg/provider/awsecs`) runs against LocalStack. ECS is not in the free LocalStack plan, so the test needs a LocalStack auth token with ECS access. Without the token, the test skips.

```bash
LOCALSTACK_AUTH_TOKEN=<token> go test -tags=nomsgpack -run TestECSProvider_Integration ./pkg/provider/awsecs/
```

In CI, the `Integration (ECS)` workflow reads the token from the `LOCALSTACK_AUTH_TOKEN` repository secret. GitHub does not pass secrets to pull requests from forks, so this test runs only for branches of this repository.

## Submitting Your Contribution

### Before Submitting

```bash
make fmt
make test
make lint
make check-generate
```

If you changed CLI flags, labels, metrics, the theme schema, or the HTTP API, run `make generate` and commit the regenerated files.


### Create a Pull Request

1. **Push your branch**:
   ```bash
   git push origin my-new-feature
   ```

2. **Open a Pull Request** on GitHub:
   - Go to your fork on GitHub
   - Click "Compare & pull request"
   - Fill in the PR template with:
     - Description of changes
     - Related issues (if any)
     - Testing done
     - Screenshots (if UI changes)

3. **PR Title**: Follow conventional commit format:
   ```
   feat(provider): add Podman support
   fix(api): resolve session race condition
   ```

4. **Address review comments**:
   - Make requested changes
   - Push additional commits
   - Re-request review when ready

### After Merge

Your changes will be included in the next release. Thank you for contributing! 🎉

---

## Getting Help

- **Discord**: Join our [Discord server](https://discord.gg/WXYp59KeK9) for discussions and support
- **Issues**: Check [existing issues](https://github.com/sablierapp/sablier/issues) or create a new one
- **Documentation**: Read the [full documentation](https://sablierapp.dev)

---

## Code of Conduct

Please note that this project is released with a [Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

---

## License

By contributing to Sablier, you agree that your contributions will be licensed under the [AGPL-3.0 License](LICENSE).

---

Thank you for contributing to Sablier! 🚀