DEVELOPER.md

Developer Guide for Porch

Extending Porch

Porch is designed to be extensible, allowing developers to add new commands and features easily. Here’s how you can extend Porch:

Adding a New YAML Command

1. Create a directory for your command under internal/commands.

2. Create a definition.go file for your command, e.g., mycommand.go that inherits the *commands.BaseCommand type.

3. Create a register.go file to register the command with the supplied registry:

   const commandType = "mycommand"
   
   // Register registers the command in the given registry.
   func Register(r commandregistry.Registry) {
     err := r.Register(commandType, &Commander{})
     if err != nil {
       panic(err)
     }
   }

4. Implement the commands.Commander interface to define your command's behavior. This should create a type that implements the runbatch.Runnable interface.

5. Implement the schema.Provider interface to provide information for command help.

6. Implement the schema.Writer interface to handle writing command help.

7. Write tests for your command in a _test.go file within the same directory.

8. Write integration tests in a _integration_test.go file to ensure your command works as expected when executed.

9. Update the cmd/porch/main.go package to register your new command.

Result Structure

Every command execution produces detailed results with the following structure:

type Result struct {
    ExitCode  int           // Command exit code
    Error     error         // Any execution error
    StdOut    []byte        // Standard output
    StdErr    []byte        // Standard error
    Label     string        // Command label/name
    Children  Results       // Nested command results
}

Every command should return a Results object that contains at least one Result object, which can be used to format output or handle errors.

🧪 Testing

Run the test suite:

# Run all tests
make test

# Run tests with coverage
make testcover

# Run linter
make lint

# Run tests with race detection
make testrace

The project includes comprehensive tests covering:

• Unit tests for all components
• Integration tests for command execution
• Error handling scenarios
• Signal handling behavior
• Result formatting and output

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository

   git clone https://github.com/yourusername/porch.git

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Add tests for new functionality
   • Update documentation as needed
   • Follow Go best practices and conventions

4. Run tests and linting

   make test
   make lint

5. Commit and push

   git commit -m 'Add amazing feature'
   git push origin feature/amazing-feature

6. Open a Pull Request

Debugging

• Most example commands are bash based, so make sure you are running in an environment that supports bash. E.g. on Windows open VSCode from WSL

• Create a launch.json file like this:

  {
     "version": "0.2.0",
     "configurations": [
        {
           "name": "Launch Package",
           "type": "go",
           "request": "launch",
           "mode": "debug",
           "program": "${workspaceRoot}/cmd/porch/main.go",
           "env": { "AVM_TEST_TYPE": "integration", "PORCH_LOG_LEVEL": "DEBUG" },
           "args": [ "run", "-f", "${workspaceRoot}/examples/complex-nested.yml", "-config-timeout", "10000", "-show-details" ],
           "cwd": "${workspaceRoot}/../terraform-azurerm-lz-vending-test"
        }
     ]
  }

  • args: The is the porch config you want to debug
  • cwd: This the target folder structure you want to run the command against
  • env: This is any environment variables needed by your porch config

• Set your break points and Run the VSCode debugger

NOTE: If you see a Delve related issue, try installing the latest version from trunk: go install -v github.com/go-delve/delve/cmd/dlv@master

Development Guidelines

• Write comprehensive tests for new features
• Follow the existing code style and patterns
• Update documentation for user-facing changes
• Use meaningful commit messages
• Keep pull requests focused and atomic