Skip to content

Commit c578b79

Browse files
committed
docs: simplify examples and reorganize README
- Remove "Basic job with retry" section (redundant with Quickstart) - Add name field to Quickstart example - Move Formats section before Configuration for better readability - Improve time format notes (10 am works, 10 alone does not) - Condense CLAUDE.md full syntax example
1 parent 4ca27af commit c578b79

2 files changed

Lines changed: 38 additions & 72 deletions

File tree

CLAUDE.md

Lines changed: 17 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -182,45 +182,25 @@ Standard cron syntax is tried first; English is used as fallback.
182182
### Full syntax (all options)
183183
184184
```yaml
185-
runner: # Optional: global settings
186-
timezone: Asia/Tokyo # Optional: IANA name, "inherit" (system), or omit for UTC
187-
env_file: .env # Optional: load env vars from file
188-
env: # Optional: inline env vars
189-
KEY: value
190-
webhook: # Optional: failure notifications (inherited by all jobs)
191-
- url: $DISCORD_WEBHOOK_URL # URL or $ENV_VAR (loaded from runner.env_file)
192-
- type: discord # Optional: defaults to "discord"
193-
url: https://discord.com/api/webhooks/...
185+
runner:
186+
timezone: Asia/Tokyo # IANA name, "inherit" (system), or omit for UTC
187+
env_file: .env
188+
env: { KEY: value }
189+
webhook:
190+
- url: $DISCORD_WEBHOOK_URL
194191

195192
jobs:
196-
<job-id>: # Key = ID (used for directories)
197-
name: "Display Name" # Optional (defaults to job-id)
198-
schedule: # String or object
199-
cron: "*/5 * * * *"
200-
timezone: Asia/Tokyo # Optional: job-level timezone override
201-
build: # Optional: string or object
202-
sh: cargo build # Build command (runs in build/ directory)
203-
timeout: 30m # Optional: timeout for build (defaults to run.timeout)
204-
working_dir: ./subdir # Optional: working directory (relative to build dir)
205-
run: # String or object
206-
sh: ./target/debug/app # Run command (runs in run/ directory)
207-
timeout: 10s # Optional (default: 1h)
208-
concurrency: skip # Optional: parallel|wait|skip|replace (default: skip)
209-
working_dir: ./subdir # Optional: working directory (relative to run dir)
210-
retry: # Optional
211-
max: 3 # Max retry attempts
212-
delay: 1s # Initial delay (default: 1s), exponential backoff
213-
jitter: 500ms # Optional: random variation 0-500ms added to retry delay
214-
# If omitted, auto-inferred as 25% of delay (e.g., 250ms for 1s delay)
215-
log: # Optional: string or object
216-
file: output.log # File path for stdout/stderr
217-
max_size: 10M # Max size before rotation (default: 10M)
218-
working_dir: ./subdir # Optional: working directory for build & run (can be overridden)
219-
env_file: .env # Optional: load env vars from file (relative to job dir)
220-
env: # Optional: inline env vars
221-
KEY: value
222-
webhook: # Optional: job-level webhooks (extend runner webhooks)
223-
- url: https://...
193+
<job-id>:
194+
name: "Display Name"
195+
schedule: { cron: "*/5 * * * *", timezone: Asia/Tokyo }
196+
build: { sh: cargo build, timeout: 30m, working_dir: ./subdir }
197+
run: { sh: ./app, timeout: 10s, concurrency: skip, working_dir: ./subdir,
198+
retry: { max: 3, delay: 1s, jitter: 500ms } }
199+
log: { file: output.log, max_size: 10M }
200+
working_dir: ./subdir
201+
env_file: .env
202+
env: { KEY: value }
203+
webhook: [{ url: https://... }]
224204
```
225205
226206
## Runtime Directory Layout

README.md

Lines changed: 21 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ cargo install --path .
1515
```yaml
1616
jobs:
1717
hello:
18+
name: "Hello World"
1819
schedule: "*/5 * * * *"
1920
run: echo "Hello from rollcron!"
2021
```
@@ -34,21 +35,6 @@ rollcron https://github.com/user/repo --pull-interval 300
3435

3536
## Examples
3637

37-
### Basic job with retry
38-
39-
```yaml
40-
jobs:
41-
backup:
42-
name: "Daily Backup"
43-
schedule: "0 2 * * *"
44-
run:
45-
sh: ./scripts/backup.sh
46-
timeout: 5m
47-
retry:
48-
max: 3
49-
delay: 10s
50-
```
51-
5238
### Human-readable schedules
5339

5440
```yaml
@@ -167,6 +153,26 @@ Options:
167153
--pull-interval <SECS> Pull interval in seconds [default: 3600]
168154
```
169155
156+
### Formats
157+
158+
**Duration**: `500ms`, `30s`, `5m`, `1h`
159+
160+
**Size**: `512K`, `10M`, `1G`, or bytes
161+
162+
**Schedule**: Cron or English phrase
163+
164+
- Cron: `min hour day month weekday` (e.g., `*/5 * * * *`)
165+
- English examples:
166+
- `every 5 minutes`
167+
- `every day at 16:00`
168+
- `7pm every Thursday`
169+
- `noon` / `midnight`
170+
171+
Notes:
172+
- Time formats: `10 am`, `10:00 am`, `10:00` work; `10` alone does not
173+
- `every day` is optional: `noon` = `noon every day`
174+
- Avoid `12 am`/`12 pm` (confusing: 12 am = midnight, 12 pm = noon): use `noon`/`midnight` or `0:00`/`12:00`
175+
170176
### Configuration (`rollcron.yaml`)
171177

172178
#### `runner` (optional)
@@ -259,26 +265,6 @@ Full form:
259265
| `type` | string, optional | Webhook type (default: `discord`) |
260266
| `url` | string | Webhook URL (supports `$VAR` expansion) |
261267

262-
### Formats
263-
264-
**Duration**: `500ms`, `30s`, `5m`, `1h`
265-
266-
**Size**: `512K`, `10M`, `1G`, or bytes
267-
268-
**Schedule**: Cron or English phrase
269-
270-
- Cron: `min hour day month weekday` (e.g., `*/5 * * * *`)
271-
- English examples:
272-
- `every 5 minutes`
273-
- `every day at 16:00`
274-
- `7pm every Thursday`
275-
- `noon` / `midnight`
276-
277-
Notes:
278-
- Minutes required: `at 12:00` works, `at 12` does not
279-
- `every day` is optional: `noon` = `noon every day`
280-
- Avoid `12 am`/`12 pm`: use `noon`/`midnight` or `0:00`/`12:00`
281-
282268
### Environment variable priority
283269

284270
Higher priority overrides lower:

0 commit comments

Comments
 (0)