Bug 1454343 Update taskcluster cron documentation r=dustin
authorSimon Fraser <sfraser@mozilla.com>
Tue, 17 Apr 2018 07:42:23 +0100
changeset 413890 da8af21b243efa5c5810ee43d947f43865c238e5
parent 413889 6047ab9ac46a891c430f42dbeedc4555123172bb
child 413891 0f26c7b0aa7d9a4ef77bb4819e53c46d663e88b8
push id102214
push usersfraser@mozilla.com
push dateTue, 17 Apr 2018 06:43:14 +0000
treeherdermozilla-inbound@da8af21b243e [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersdustin
bugs1454343
milestone61.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1454343 Update taskcluster cron documentation r=dustin Reviewers: dustin Reviewed By: dustin Bug #: 1454343 Differential Revision: https://phabricator.services.mozilla.com/D950
taskcluster/docs/cron.rst
--- a/taskcluster/docs/cron.rst
+++ b/taskcluster/docs/cron.rst
@@ -25,16 +25,55 @@ tree.
 
 The mach subcommand reads ``.cron.yml``, then consults the current time
 (actually the time the cron task was created, rounded down to the nearest 15
 minutes) and creates tasks for any cron jobs scheduled at that time.
 
 Each cron job in ``.cron.yml`` specifies a ``job.type``, corresponding to a
 function responsible for creating TaskCluster tasks when the job runs.
 
+Describing Time
+---------------
+
+This cron implementation understands the following directives when
+describing when to run:
+
+* ``minute``: The minute in which to run, must be in 15 minute increments (see above)
+* ``hour``: The hour of the day in which to run, in 24 hour time.
+* ``day``: The day of the month as an integer, such as `1`, `16`. Be cautious above `28`, remember February.
+* ``weekday``: The day of the week, `Monday`, `Tuesday`, etc. Full length ISO compliant words.
+
+Setting both 'day' and 'weekday' will result in a cron job that won't run very often,
+and so is undesirable.
+
+*Examples*
+
+.. code-block:: yaml
+
+    # Never
+    when: []
+
+    # 4 AM and 4 PM, on the hour, every day.
+    when:
+        - {hour: 16, minute: 0}
+        - {hour: 4, minute: 0}
+
+    # The same as above, on a single line
+    when: [{hour: 16, minute: 0}, {hour: 4, minute: 0}]
+
+    # 4 AM on the second day of every month.
+    when:
+        - {day: 2, hour: 4, minute: 0}
+
+    # Mondays and Thursdays at 10 AM
+    when:
+        - {weekday: 'Monday', hour: 10, minute: 0}
+        - {weekday: 'Thursday', hour: 10, minute: 0}
+
+
 Decision Tasks
 ..............
 
 For ``job.type`` "decision-task", tasks are created based on
 ``.taskcluster.yml`` just like the decision tasks that result from a push to a
 repository.  They run with a distinct ``taskGroupId``, and are free to create
 additional tasks comprising a task graph.