gocron: Go Job Scheduling Library

Expert assistant for working with go-co-op/gocron, a fluent Go cron scheduling library forked from jasonlvhit/gocron.

Overview

This skill helps you work with gocron, a Go library for scheduling recurring jobs. It provides guidance on building, testing, and implementing job scheduling functionality with various schedule types (duration, cron, daily, weekly, monthly), distributed locking, and job monitoring.

Key Capabilities

Step-by-Step Instructions

1. Initial Setup and Dependencies

When starting work with the gocron codebase:

1. **Install dependencies**: Run `go mod tidy`

2. **Install required tools**:

```bash

go install go.uber.org/mock/mockgen@latest

export PATH=$PATH:$(go env GOPATH)/bin

```

3. **Verify build**: Run `go build -v ./...`

4. **Generate mocks** (if interfaces changed): Run `make mocks`

**Important**: This is a library, not an application. There's no main binary to run.

2. Understanding the Repository Structure

Key files you'll work with:

3. Making Code Changes

Before modifying code:

1. **Read the target file first** - Never propose changes without reading existing code

2. **Run tests to establish baseline**: `make test` (takes ~50 seconds, DO NOT CANCEL)

3. **Make focused changes** - Only change what's necessary for the task

4. **Avoid over-engineering** - No extra features, comments, or refactoring unless requested

After making changes:

1. **Format code**: `make fmt`

2. **Regenerate mocks** (if interfaces changed): `make mocks`

3. **Run tests**: `make test` with 90+ second timeout

4. **Verify examples still work**: `cd examples/elector && go run main.go`

4. Testing Strategy

**Always run tests before submitting changes.**

**Never cancel long-running tests** - they legitimately take 50+ seconds.

Testing patterns in this codebase:

5. Manual Validation

Since this is a library, validate functionality by:

**Basic validation script** (save as `test_validation.go`):

```go

package main

import (

"fmt"

"time"

"github.com/go-co-op/gocron/v2"

)

func main() {

s, err := gocron.NewScheduler()

if err != nil {

panic(err)

}

j, err := s.NewJob(

gocron.DurationJob(2*time.Second),

gocron.NewTask(func() {

fmt.Println("Working!")

}),

)

if err != nil {

panic(err)

}

fmt.Printf("Job ID: %s\n", j.ID())

s.Start()

time.Sleep(6 * time.Second)

s.Shutdown()

}

```

Run with: `go run test_validation.go`

**Expected output**: "Working!" printed 2-3 times with 2-second intervals.

6. Linting and Formatting

**Required before submission**:

**Optional linting**:

**Special validation**:

7. Common Tasks and Solutions

**Adding a new job definition type**:

1. Add interface implementation in `job.go`

2. Update tests in `job_test.go`

3. Regenerate mocks: `make mocks`

4. Add example in `examples/`

5. Run full test suite

**Modifying scheduler behavior**:

1. Update `scheduler.go`

2. Update corresponding tests

3. Check if examples need updates

4. Verify distributed behavior if applicable

**Adding monitoring or logging**:

1. Update interface in `monitor.go` or `logger.go`

2. Regenerate mocks: `make mocks`

3. Update implementations

4. Add tests

8. Troubleshooting Common Issues

**mockgen not found**:

```bash

go install go.uber.org/mock/mockgen@latest

export PATH=$PATH:$(go env GOPATH)/bin

```

**Test timeouts**:

**golangci-lint errors**:

**Import errors in examples**:

**PATH issues**:

Constraints and Requirements

Key Dependencies

Automatically managed via `go mod`:

Expected Timings

References