whenever 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55cafb2edffbfeec94032659d8af2086785d5c864c7e979395197ba02e6612d4
-  data.tar.gz: 88ad009fb54d433ac00fd86f24c8ca0a5cbe05f7cd7774a8b4fac1ebfb90c4b9
+  metadata.gz: 85714fb8b50231a67eca8db2f67211fc11e8bb07bbb76db5333882676f626802
+  data.tar.gz: 9523c1ec86b34bd8fcd9244ebbc37206857ef25bdcce6cbb661769e9231d3ed5
 SHA512:
-  metadata.gz: a81a8c3345588bf311b35bb9b6a6d158dd3fcff181f5a67c423a12db336ccc21c802d1f9498ecd079ebe2006479c971abc7a9129a89c965f63a88a46e1aee78d
-  data.tar.gz: 35622000e04945eab6965f0b5b87a2f2e914753628cf8ccbcf1e9cf99cbf0182125c283ad593f34a1dfa9372c225d208239fd9cec3a1d507a9a34f711f8da99f
+  metadata.gz: bd84f4e82fcd6aff274fef804ca4fd2e834d6817778fd09d56287a013039005e1ecaeb12e8fde657502709bcabcd8dc31bdd0d99cd163edefe1d0b8889d2a78d
+  data.tar.gz: 59728cc54eae8cd88fe0d911ff6bb2a5571fdc0f257dc93ab8564c3d7795f7583aece8c21eede62ae6b99b5a264c3b4ece7e222dac77f3a2b1401f3f3237605b

data/.github/workflows/ci.yml

@@ -3,6 +3,8 @@ on:
   pull_request:
   push:
     branches: [ main ]
+permissions:
+  contents: read
 jobs:
   test:
     runs-on: ${{ matrix.os }}
@@ -10,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby-version: [ '2.4', '2.5', '2.6', '2.7', '3.0', '3.0', '3.2', '3.3', '3.4', 'jruby-9', 'jruby-10']
+        ruby-version: [ '2.4', '2.5', '2.6', '2.7', '3.0', '3.0', '3.2', '3.3', '3.4', '4.0', 'jruby-9', 'jruby-10']
         # CRuby < 2.6 does not support macos-arm64, so test those on amd64 instead
         exclude:
           - os: macos-latest
@@ -18,12 +20,12 @@ jobs:
           - os: macos-latest
             ruby-version: '2.5'
         include:
-          - os: macos-13
+          - os: macos-15-intel
             ruby-version: '2.4'
-          - os: macos-13
+          - os: macos-15-intel
             ruby-version: '2.5'
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         name: Set up Ruby ${{ matrix.ruby-version }}
       - uses: ruby/setup-ruby@v1
         env:
@@ -42,7 +44,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['2.7', '3.0', '3.0', '3.2', '3.3', '3.4']
+        ruby-version: ['2.7', '3.0', '3.0', '3.2', '3.3', '3.4', '4.0']
         rails-version: ['6.0', '6.1', '7.0', '7.1', '7.2', '8.0', '8.1']
         include:
           - ruby-version: 2.7
@@ -74,7 +76,7 @@ jobs:
     env:
       BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/activesupport${{ matrix.rails-version }}.gemfile
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         name: Set up Ruby ${{ matrix.ruby-version }}
       - uses: ruby/setup-ruby@v1
         with:

data/CHANGELOG.md

@@ -1,7 +1,26 @@
 ### unreleased
 
 
-### 1.1.1 / Dec 8, 2025
+### 1.1.3 / September 15, 2026
+
+* Add support for sequential job definitions https://github.com/javan/whenever/pull/854
+
+* CI: Bump actions/checkout from 6 to 7 https://github.com/javan/whenever/pull/876
+
+* CI: Restrict GitHub Actions workflow permissions to contents: read https://github.com/javan/whenever/pull/875
+
+
+### 1.1.2 / January 18, 2026
+
+* Add description as comment in crontab https://github.com/javan/whenever/pull/776
+
+* Override global option with group option https://github.com/javan/whenever/pull/822
+
+* CI: Add Ruby 4.0 to CI Matrix https://github.com/javan/whenever/pull/872
+
+* CI: Use macos-15-intel instead of macos-13 for Ruby 2.4 and 2.5 https://github.com/javan/whenever/pull/871
+
+### 1.1.1 / December 8, 2025
 
 * job_list `.respond_to?` updated to an instance method https://github.com/javan/whenever/pull/830
 
@@ -13,7 +32,7 @@
 
 * Require MFA for gem releases https://github.com/javan/whenever/pull/867
 
-### 1.1.0 / Nov 21, 2025
+### 1.1.0 / November 21, 2025
 
 * Splat whenever_roles when passing to roles https://github.com/javan/whenever/pull/777
 
@@ -151,7 +170,7 @@
 * Process params in job templates. [Austin Ziegler]
 
 
-### 0.8.4 / July 22, 2012
+### 0.8.4 / July 22, 2013
 
 * Don't require schedule file when clearing. [Javan Makhmali]
 

data/README.md

@@ -59,6 +59,14 @@ every 3.hours do # 1.minute 1.day 1.week 1.month 1.year is also supported
   command "/usr/bin/my_great_command"
 end
 
+every 3.hours, sequential: true do
+  # Jobs in this block that don't set their own sequence will default to run in the same sequence (not in parallel)
+  runner "MyModel.some_process", halt_sequence_on_failure: true # If this job fails, subsequent jobs will not run (defaults to false)
+  rake "my:rake:task"
+  command "/usr/bin/my_great_command", sequence: nil # This job runs in parallel with other jobs that are not part of a sequence
+  runner "MyModel.task_to_run_at_four_thirty_in_the_morning", sequence: 'other' # This job runs sequentially with other jobs in the sequence called 'other'
+end
+
 every 1.day, at: '4:30 am' do
   runner "MyModel.task_to_run_at_four_thirty_in_the_morning"
 end
@@ -180,6 +188,26 @@ every 3.hours do
 end
 ```
 
+### Adding comments to crontab
+
+A description can be added to a job that will be included in the crontab as a comment above the cron entry.
+
+Example: A single line description:
+
+```ruby
+every 1.hours, description: "My job description" do
+  command "/usr/bin/my_great_command"
+end
+```
+
+Example: A multi line description:
+
+```ruby
+every 1.hours, description: "My job description\nhas multiple lines" do
+  command "/usr/bin/my_great_command"
+end
+```
+
 ### Capistrano integration
 
 Use the built-in Capistrano recipe for easy crontab updates with deploys. For Capistrano V3, see the next section.

data/lib/whenever/job.rb

@@ -2,7 +2,7 @@ require 'shellwords'
 
 module Whenever
   class Job
-    attr_reader :at, :roles, :mailto
+    attr_reader :at, :roles, :mailto, :description, :sequence, :halt_sequence_on_failure
 
     def initialize(options = {})
       @options = options
@@ -10,7 +10,10 @@ module Whenever
       @template                         = options.delete(:template)
       @mailto                           = options.fetch(:mailto, :default_mailto)
       @job_template                     = options.delete(:job_template) || ":job"
+      @sequence                         = options.delete(:sequence)
+      @halt_sequence_on_failure         = options.delete(:halt_sequence_on_failure)
       @roles                            = Array(options.delete(:roles))
+      @description                      = options.delete(:description)
       @options[:output]                 = options.has_key?(:output) ? Whenever::Output::Redirection.new(options[:output]).to_s : ''
       @options[:environment_variable] ||= "RAILS_ENV"
       @options[:environment]          ||= :production

data/lib/whenever/job_list.rb

@@ -48,6 +48,12 @@ module Whenever
     def every(frequency, options = {})
       @current_time_scope = frequency
       @options = options
+
+      if @options[:sequential]
+        @default_sequence_id ||= 0
+        @options[:sequence] ||= "default_sequence_#{@default_sequence_id += 1}"
+      end
+
       yield
     end
 
@@ -66,7 +72,7 @@ module Whenever
 
           @jobs[options.fetch(:mailto)] ||= {}
           @jobs[options.fetch(:mailto)][@current_time_scope] ||= []
-          @jobs[options.fetch(:mailto)][@current_time_scope] << Whenever::Job.new(@options.merge(@set_variables).merge(options))
+          @jobs[options.fetch(:mailto)][@current_time_scope] << Whenever::Job.new(@set_variables.merge(@options).merge(options))
         end
       end
     end
@@ -138,12 +144,20 @@ module Whenever
     def cron_jobs_of_time(time, jobs)
       shortcut_jobs, regular_jobs = [], []
 
+      filtered_jobs = jobs.select do |job|
+        roles.empty? || roles.any? { |r| job.has_role?(r) }
+      end
+
+      grouped_jobs = filtered_jobs.group_by(&:sequence)
+      grouped_jobs.each do |sequence, jobs|
+        grouped_jobs[sequence] = JobSequence.new(jobs) if sequence
+      end
+      jobs = grouped_jobs.values.flatten
+
       jobs.each do |job|
-        next unless roles.empty? || roles.any? do |r|
-          job.has_role?(r)
-        end
         Whenever::Output::Cron.output(time, job, :chronic_options => @chronic_options) do |cron|
           cron << "\n\n"
+          cron = (job.description.strip + "\n").gsub(/^(.*)$/, '# \1') + cron unless job.description.to_s.empty?
 
           if cron[0,1] == "@"
             shortcut_jobs << cron

data/lib/whenever/job_sequence.rb

@@ -0,0 +1,36 @@
+require 'shellwords'
+
+module Whenever
+  class JobSequence
+    attr_reader :at, :roles, :mailto, :description
+
+    def initialize(jobs, options = {})
+      validate!(jobs)
+
+      @jobs        = jobs
+      @options     = options
+      @at          = options.fetch(:at, primary_job.at)
+      @mailto      = options.fetch(:mailto, primary_job.mailto || :default_mailto)
+      @roles       = Array(options.delete(:roles), *primary_job.roles)
+      @description = options.fetch(:description) { @jobs.map { |job| job.description.to_s.strip }.reject(&:empty?).uniq.join("\n") }
+    end
+
+    def output
+      @jobs.map { |job| [job.output, job.halt_sequence_on_failure ?  ' && ' : ' ; '] }.flatten[0..-2].join
+    end
+
+    def has_role?(role)
+      roles.empty? || roles.include?(role)
+    end
+
+  private
+
+    def primary_job
+      @jobs.first
+    end
+
+    def validate!(jobs)
+      raise ArgumentError, "Jobs in a sequence don't support different `at` values" if jobs.map(&:at).uniq.count > 1
+    end
+  end
+end

data/lib/whenever/version.rb

@@ -1,3 +1,3 @@
 module Whenever
-  VERSION = '1.1.1'
+  VERSION = '1.1.3'
 end

data/lib/whenever.rb

@@ -2,6 +2,7 @@ require "whenever/version"
 require 'whenever/numeric'
 require 'whenever/numeric_seconds'
 require 'whenever/job_list'
+require 'whenever/job_sequence'
 require 'whenever/job'
 require 'whenever/command_line'
 require 'whenever/cron'

data/test/functional/output_defined_job_test.rb

@@ -55,6 +55,34 @@ class OutputDefinedJobTest < Whenever::TestCase
     assert_match(/^.+ .+ .+ .+ before during after local$/, output)
   end
 
+  test "defined job with a :task and an option where the option is set globally and on the group" do
+    output = Whenever.cron \
+    <<-file
+      set :job_template, nil
+      job_type :some_job, "before :task after :option1"
+      set :option1, 'global'
+      every 2.hours, :option1 => 'group' do
+        some_job "during"
+      end
+    file
+
+    assert_match(/^.+ .+ .+ .+ before during after group$/, output)
+  end
+
+  test "defined job with a :task and an option where the option is set globally, on the group, and locally" do
+    output = Whenever.cron \
+    <<-file
+      set :job_template, nil
+      job_type :some_job, "before :task after :option1"
+      set :option1, 'global'
+      every 2.hours, :option1 => 'group' do
+        some_job "during", :option1 => 'local'
+      end
+    file
+
+    assert_match(/^.+ .+ .+ .+ before during after local$/, output)
+  end
+
   test "defined job with a :task and an option that is not set" do
     output = Whenever.cron \
     <<-file

data/test/functional/output_description_test.rb

@@ -0,0 +1,25 @@
+require 'test_helper'
+
+class OutputDescriptionTest < Whenever::TestCase
+  test "single line description" do
+    output = Whenever.cron \
+    <<-file
+      every "weekday", :description => "A description" do
+        command "blahblah"
+      end
+    file
+
+    assert_match "# A description\n0 0 * * 1-5 /bin/bash -l -c 'blahblah'\n\n", output
+  end
+
+  test "multi line description" do
+    output = Whenever.cron \
+    <<-file
+      every "weekday", :description => "A description\nhas mulitple lines" do
+        command "blahblah"
+      end
+    file
+
+    assert_match "# A description\n# has mulitple lines\n0 0 * * 1-5 /bin/bash -l -c 'blahblah'\n\n", output
+  end
+end

data/test/functional/output_jobs_with_sequence_test.rb

@@ -0,0 +1,187 @@
+require 'test_helper'
+
+class OutputJobsWithSequenceTest < Whenever::TestCase
+  test "defined jobs with a sequence argument specified per-job" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours do
+        command "blahblah", sequence: 'backups'
+        command "foofoo", sequence: 'backups'
+        command "barbar"
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah' ; /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'barbar'", output_without_empty_line.shift
+  end
+
+  test "defined jobs with a sequence argument specified on the group" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups' do
+        command "blahblah"
+        command "foofoo"
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah' ; /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+  end
+
+  test "defined jobs with a sequence argument and a job that halts the sequence on failure" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups' do
+        command "blahblah", halt_sequence_on_failure: true
+        command "foofoo"
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah' && /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+  end
+
+  test "defined jobs with a sequences specified on the group and jobs" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups' do
+        command "blahblah"
+        command "barbar", sequence: nil
+        command "foofoo"
+        command "bazbaz", sequence: 'bees'
+        command "buzzbuzz", sequence: 'bees'
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah' ; /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'barbar'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'bazbaz' ; /bin/bash -l -c 'buzzbuzz'", output_without_empty_line.shift
+  end
+
+  test "defined jobs with a multiple groups with sequences specified on the group and jobs" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups' do
+        command "blahblah"
+        command "barbar", sequence: nil
+        command "bazbaz", sequence: 'bees'
+      end
+
+      every 2.hours, sequence: 'backups' do
+        command "foofoo"
+        command "buzzbuzz", sequence: 'bees'
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah' ; /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'barbar'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'bazbaz' ; /bin/bash -l -c 'buzzbuzz'", output_without_empty_line.shift
+  end
+
+  test "defined jobs with a multiple groups with sequences specified on the group and jobs" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups' do
+        command "blahblah"
+        command "barbar", sequence: nil
+        command "bazbaz", sequence: 'bees'
+      end
+
+      every 3.hours, sequence: 'backups' do
+        command "foofoo"
+        command "buzzbuzz", sequence: 'bees'
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'barbar'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'bazbaz'", output_without_empty_line.shift
+    assert_equal three_hours + " /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+    assert_equal three_hours + " /bin/bash -l -c 'buzzbuzz'", output_without_empty_line.shift
+  end
+
+  test "defined jobs with a multiple groups with sequences specified on the group and jobs" do
+    assert_raises ArgumentError do
+      Whenever.cron \
+      <<-file
+        every 2.hours, sequence: 'backups' do
+          command "blahblah", at: 1
+          command "barbar", at: 2
+        end
+      file
+    end
+  end
+
+  test "defined jobs with a sequence argument and a description on the group" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups', description: "Nightly backups" do
+        command "blahblah"
+        command "foofoo"
+      end
+    file
+
+    assert_match "# Nightly backups\n" + two_hours + " /bin/bash -l -c 'blahblah' ; /bin/bash -l -c 'foofoo'", output
+  end
+
+  test "defined jobs with a sequence argument and a description on each job" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups' do
+        command "blahblah", description: "Dump the database"
+        command "foofoo", description: "Upload the dump"
+      end
+    file
+
+    assert_match "# Dump the database\n# Upload the dump\n" + two_hours + " /bin/bash -l -c 'blahblah' ; /bin/bash -l -c 'foofoo'", output
+  end
+
+  test "defined jobs with a sequence argument and descriptions padded with whitespace" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequence: 'backups' do
+        command "blahblah", description: "  Dump the database  "
+        command "foofoo", description: "  Upload the dump  "
+      end
+    file
+
+    assert_match "# Dump the database\n# Upload the dump\n" + two_hours, output
+  end
+
+  def three_hours
+    "0 0,3,6,9,12,15,18,21 * * *"
+  end
+end
+
+class OutputJobsWithSequentialTest < Whenever::TestCase
+  test "defined jobs with a sequential argument" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequential: true do
+        command "blahblah"
+        command "foofoo"
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah' ; /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+  end
+
+  test "defined jobs with a sequential argument" do
+    output = Whenever.cron \
+    <<-file
+      every 2.hours, sequential: true do
+        command "blahblah"
+        command "foofoo", sequence: false
+      end
+    file
+
+    output_without_empty_line = lines_without_empty_line(output.lines)
+    assert_equal two_hours + " /bin/bash -l -c 'blahblah'", output_without_empty_line.shift
+    assert_equal two_hours + " /bin/bash -l -c 'foofoo'", output_without_empty_line.shift
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whenever
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.3
 platform: ruby
 authors:
 - Javan Makhmali
@@ -65,6 +65,7 @@ files:
 - lib/whenever/cron.rb
 - lib/whenever/job.rb
 - lib/whenever/job_list.rb
+- lib/whenever/job_sequence.rb
 - lib/whenever/numeric.rb
 - lib/whenever/numeric_seconds.rb
 - lib/whenever/os.rb
@@ -75,9 +76,11 @@ files:
 - test/functional/output_at_test.rb
 - test/functional/output_default_defined_jobs_test.rb
 - test/functional/output_defined_job_test.rb
+- test/functional/output_description_test.rb
 - test/functional/output_env_test.rb
 - test/functional/output_jobs_for_roles_test.rb
 - test/functional/output_jobs_with_mailto_test.rb
+- test/functional/output_jobs_with_sequence_test.rb
 - test/functional/output_redirection_test.rb
 - test/test_case.rb
 - test/test_helper.rb
@@ -108,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Cron jobs in ruby.
 test_files:
@@ -116,9 +119,11 @@ test_files:
 - test/functional/output_at_test.rb
 - test/functional/output_default_defined_jobs_test.rb
 - test/functional/output_defined_job_test.rb
+- test/functional/output_description_test.rb
 - test/functional/output_env_test.rb
 - test/functional/output_jobs_for_roles_test.rb
 - test/functional/output_jobs_with_mailto_test.rb
+- test/functional/output_jobs_with_sequence_test.rb
 - test/functional/output_redirection_test.rb
 - test/unit/capistrano_support_test.rb
 - test/unit/cron_test.rb