Skip to content

Latest commit

 

History

History
200 lines (150 loc) · 6.14 KB

CONTRIBUTING.MD

File metadata and controls

200 lines (150 loc) · 6.14 KB

Contributing Guide

⚙️ Prerequisites

Ensure these tools are installed before you begin:

Windows Setup

  1. Go: Download from golang.org, install, and verify with go version

  2. Air:

    go install github.com/air-verse/air@v1.61.5

    Add %USERPROFILE%\go\bin to your PATH

  3. Docker Desktop: Download from docker.com, enable WSL 2 during installation

  4. Templ:

    go install github.com/a-h/templ/cmd/templ@v0.3.857

  5. TailwindCSS: Using npm (requires Node.js):

    npm install -g tailwindcss

    Or with standalone executable:

    curl.exe -sLO https://github.com/tailwindlabs/tailwindcss/releases/v3.4.13/download/tailwindcss-windows-x64.exe
rename tailwindcss-windows-x64.exe tailwindcss.exe

  6. golangci-lint:

    curl.exe -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.ps1 | powershell -Command -

🛠️ Development Setup

  1. Clone the repository:

    git clone https://github.com/iota-uz/iota-sdk.git
cd iota-sdk

  2. Create env file:

    cp .env.example .env

    Windows: copy .env.example .env

  3. Install dependencies:

    make deps

    Windows: If make is unavailable, install via GnuWin32 or use Git Bash

  4. Run PostgreSQL:

    make localdb

    Ensure Docker is running before executing this command

  5. Apply migrations:

    make migrate up && make seed

  6. Run TailwindCSS in watch mode (new terminal):

    make css-watch

  7. Start development server:

    air

  8. Access the application:

🧪 Running Tests

To run end-to-end Cypress tests:

  1. Ensure you have a migrated and seeded database with a running backend
  2. Set environment variables (DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, DB_NAME) or use default local settings
  3. Run the tests: 
    cd e2e/
pnpm cypress run --headed

📚 Documentation

Generate code documentation:

# For entire project
make docs

# With specific options
go run cmd/document/main.go -dir [directory] -out [output file] [-recursive] [-exclude "dir1,dir2"]

Options:

  • -dir: Target directory (default: current directory)
  • -out: Output file path (default: DOCUMENTATION.md)
  • -recursive: Process subdirectories
  • -exclude: Skip specified directories (comma-separated)

Explicitly Name Database Constraints

When defining or altering table schemas in .sql files that are processed by the schema/collector (both in db/migrations/ and embedded module schemas):

IMPORTANT NOTE:

Migration tool only supports UNIQUE constraints (other constraints are not yet supported). Keep this in mind when mutating schemas. Changes in configuration such as altering varchar(255) to varchar(500) or changing datetime from null to now() are not handled. TODO list of limitations.

All constraints (PRIMARY KEY, UNIQUE, FOREIGN KEY, CHECK) MUST be explicitly named using the CONSTRAINT <constraint_name> syntax.

Reasoning:

The schema/collector tool automatically generates Up and Down migration scripts by comparing schema states. To create correct DROP CONSTRAINT commands (especially critical for Down migrations and for modifying existing constraints), the tool relies on predictable constraint names. Database auto-generated names are inconsistent and difficult for the tool to determine reliably, leading to potential migration failures. Explicit naming ensures that schema comparisons and generated migrations are accurate and robust.

Recommended Naming Convention:

Please use the following convention for consistency:

<table>_<column(s)>_<type_suffix>

Suffixes:

  • _pkey for Primary Keys
  • _key for Unique Constraints (please be consistent within the project)
  • _fk for Foreign Keys
  • _check for Check Constraints

Note: For multi-column constraints, include relevant column names separated by underscores if feasible, or provide a meaningful description.

This documentation provides context for LLMs working on the IOTA-SDK project.

❓ Known Issues and Troubleshooting

Linting Issues

Do not run

golangci-lint run --fix

It will break the code.

When facing an error like this:

WARN [runner] Can't run linter goanalysis_metalinter: buildssa: failed to load package : could not load export data: no
export data for "github.com/iota-uz/iota-sdk/modules/core/domain/entities/expense_category"

Try running:

go mod tidy

Windows Setup Issues

  1. Make commands fail:

    • Install via GnuWin32
    • Add installation directory to PATH
    • Or use Git Bash which includes Make

  2. Docker issues:

    • Ensure WSL 2 is properly configured
    • Run wsl --update as administrator
    • Restart Docker Desktop

  3. Air hot-reloading problems:

    • Verify Air is in your PATH
    • Check for .air.toml configuration
    • Try air init to create new configuration

  4. PostgreSQL connection issues:

    • Ensure Docker is running
    • Check container status: docker ps
    • Verify database credentials in .env

🤝 Communication Guidelines

Contributors should close conversations when complete. Reviewers may reopen if needed.

For additional help, see our FAQ or open a GitHub issue.