Merge branch 'v2' into feature/scheduler-monitor

.github/workflows/go_test.yml

@@ -24,7 +24,7 @@ jobs:
         with:
           go-version: ${{ matrix.go-version }}
       - name: golangci-lint
-        uses: golangci/golangci-lint-action@v8.0.0
+        uses: golangci/golangci-lint-action@v9.0.0
         with:
           version: v2.4.0
       - name: test

errors.go

@@ -61,6 +61,7 @@ var (
 	ErrStopTimeEarlierThanStartTime  = errors.New("gocron: WithStopDateTime: end must not be earlier than start")
 	ErrWithStopTimeoutZeroOrNegative = errors.New("gocron: WithStopTimeout: timeout must be greater than 0")
 	ErrWithSchedulerMonitorNil       = errors.New("gocron: WithSchedulerMonitor: scheduler monitor cannot be nil")
+	ErrWithLimitedRunsZero           = errors.New("gocron: WithLimitedRuns: limit must be greater than 0")
 )
 
 // internal errors

job.go

@@ -643,6 +643,9 @@ func WithEventListeners(eventListeners ...EventListener) JobOption {
 // Upon reaching the limit, the job is removed from the scheduler.
 func WithLimitedRuns(limit uint) JobOption {
 	return func(j *internalJob, _ time.Time) error {
+		if limit == 0 {
+			return ErrWithLimitedRunsZero
+		}
 		j.limitRunsTo = &limitRunsTo{
 			limit:    limit,
 			runCount: 0,

job_test.go

@@ -44,6 +44,9 @@ func TestDurationJob_next(t *testing.T) {
 }
 
 func TestDailyJob_next(t *testing.T) {
+	americaChicago, err := time.LoadLocation("America/Chicago")
+	require.NoError(t, err)
+
 	tests := []struct {
 		name                      string
 		interval                  uint
@@ -84,6 +87,16 @@ func TestDailyJob_next(t *testing.T) {
 			time.Date(2000, 1, 3, 5, 30, 0, 0, time.UTC),
 			41 * time.Hour,
 		},
+		{
+			"daily at time with daylight savings time",
+			1,
+			[]time.Time{
+				time.Date(0, 0, 0, 5, 30, 0, 0, americaChicago),
+			},
+			time.Date(2023, 3, 11, 5, 30, 0, 0, americaChicago),
+			time.Date(2023, 3, 12, 5, 30, 0, 0, americaChicago),
+			23 * time.Hour,
+		},
 	}
 
 	for _, tt := range tests {
@@ -101,6 +114,9 @@ func TestDailyJob_next(t *testing.T) {
 }
 
 func TestWeeklyJob_next(t *testing.T) {
+	americaChicago, err := time.LoadLocation("America/Chicago")
+	require.NoError(t, err)
+
 	tests := []struct {
 		name                      string
 		interval                  uint
@@ -132,6 +148,17 @@ func TestWeeklyJob_next(t *testing.T) {
 			time.Date(2000, 1, 10, 5, 30, 0, 0, time.UTC),
 			4 * 24 * time.Hour,
 		},
+		{
+			"last run before daylight savings time, next run after",
+			1,
+			[]time.Weekday{time.Saturday},
+			[]time.Time{
+				time.Date(0, 0, 0, 5, 30, 0, 0, americaChicago),
+			},
+			time.Date(2023, 3, 11, 5, 30, 0, 0, americaChicago),
+			time.Date(2023, 3, 18, 5, 30, 0, 0, americaChicago),
+			7*24*time.Hour - time.Hour,
+		},
 	}
 
 	for _, tt := range tests {

migration_v1_to_v2.md

@@ -0,0 +1,155 @@
+# Migration Guide: `gocron` v1 → v2
+
+This guide helps you migrate your code from the `v1` branch to the `v2` branch of [go-co-op/gocron](https://github.com/go-co-op/gocron).
+Version 2 is a major rewrite focusing on improving the internals of gocron, while also enhancing the user interfaces and error handling.
+All major functionality has been ported over.
+
+---
+
+## Table of Contents
+
+- [Overview of Major Changes](#overview-of-major-changes)
+- [Installation](#installation)
+- [API Changes](#api-changes)
+- [Scheduler Creation](#scheduler-creation)
+- [Job Definition](#job-definition)
+- [Starting and Stopping the Scheduler](#starting-and-stopping-the-scheduler)
+- [Error Handling](#error-handling)
+- [Distributed Scheduling](#distributed-scheduling)
+- [Examples Migration](#examples-migration)
+- [Testing and Validation](#testing-and-validation)
+- [Troubleshooting](#troubleshooting)
+- [References](#references)
+
+---
+
+## Overview of Major Changes
+
+- **Breaking API changes**: All major interfaces and types have changed.
+- **Improved error reporting**: Most functions now return errors.
+- **Job IDs and cancellation**: Jobs have unique IDs and can be cancelled.
+- **Distributed and monitored scheduling**: Built-in support for distributed schedulers and job monitors.
+- **Context and logging enhancements**: Improved support for cancellation, context, and custom logging interfaces.
+
+---
+
+## Installation
+
+Update your dependency to v2:
+
+```sh
+go get github.com/go-co-op/gocron/v2
+```
+
+**Note:** The import path is `github.com/go-co-op/gocron/v2`.
+
+---
+
+## API Changes
+
+### 1. Scheduler Creation
+
+**v1:**
+```go
+import "github.com/go-co-op/gocron"
+
+s := gocron.NewScheduler(time.UTC)
+```
+
+**v2:**
+```go
+import "github.com/go-co-op/gocron/v2"
+
+s, err := gocron.NewScheduler()
+if err != nil { panic(err) }
+```
+- **v2** returns an error on creation.
+- **v2** does not require a location/timezone argument. Use `WithLocation()` if needed.
+
+---
+
+### 2. Job Creation
+
+**v1:**
+```go
+s.Every(1).Second().Do(taskFunc)
+```
+
+**v2:**
+```go
+j, err := s.NewJob(
+    gocron.DurationJob(1*time.Second),
+    gocron.NewTask(taskFunc),
+)
+if err != nil { panic(err) }
+```
+- **v2** uses explicit job types (`DurationJob`, `CronJob`, etc).
+- **v2** jobs have unique IDs: `j.ID()`.
+- **v2** returns an error on job creation.
+
+#### Cron Expressions
+
+**v1:**
+```go
+s.Cron("*/5 * * * *").Do(taskFunc)
+```
+
+**v2:**
+```go
+j, err := s.NewJob(
+    gocron.CronJob("*/5 * * * *"),
+    gocron.NewTask(taskFunc),
+)
+```
+
+#### Arguments
+
+**v1:**
+```go
+s.Every(1).Second().Do(taskFunc, arg1, arg2)
+```
+
+**v2:**
+```go
+j, err := s.NewJob(
+    gocron.DurationJob(1*time.Second),
+    gocron.NewTask(taskFunc, arg1, arg2),
+)
+```
+
+---
+
+### 3. Starting and Stopping the Scheduler
+
+**v1:**
+```go
+s.StartAsync()
+s.Stop()
+```
+
+**v2:**
+```go
+s.Start()
+s.Shutdown()
+```
+
+- Always call `Shutdown()` for graceful cleanup.
+
+---
+
+### 4. Error Handling
+
+- Most v2 methods return errors. Always check `err`.
+- Use `errors.go` for error definitions.
+
+---
+
+## References
+
+- [v2 API Documentation](https://pkg.go.dev/github.com/go-co-op/gocron/v2)
+- [Examples](https://pkg.go.dev/github.com/go-co-op/gocron/v2#pkg-examples)
+- [Release Notes](https://github.com/go-co-op/gocron/releases)
+
+---
+
+**If you encounter issues, open a GitHub Issue or consider contributing a fix by checking out the [CONTRIBUTING.md](CONTRIBUTING.md) guide.**

scheduler_test.go

@@ -1056,6 +1056,14 @@ func TestScheduler_NewJobErrors(t *testing.T) {
 			[]JobOption{WithIdentifier(uuid.Nil)},
 			ErrWithIdentifierNil,
 		},
+		{
+			"WithLimitedRuns is zero",
+			DurationJob(
+				time.Second,
+			),
+			[]JobOption{WithLimitedRuns(0)},
+			ErrWithLimitedRunsZero,
+		},
 	}
 
 	for _, tt := range tests {