docs(cron): using-cron page says sub-minute scheduling is impossible, then demonstrates it

[akshat-kumar-singhal]

Describe the bug

docs/advanced-guide/using-cron/page.md contradicts itself about whether cron jobs can run more than once a minute, and the sentence that is wrong is the one a reader is most likely to act on.

:39 states:

The minimum time difference between cron job's two consecutive runs is a minute as it is the least significant scheduling time parameter.

Ten lines above, :29-31 documents the optional leading second field:

GoFr also allows an optional field for second as first part in the schedule format, like in the following format:
second minute hour day_of_month month day_of_week

and the page's own example at :77 uses it:

// Run the cron job every 10 seconds(*/10)
app.AddCronJob("*/10 * * * * *", "", func(ctx *gofr.Context) {
    ctx.Logger.Infof("current time is %v", time.Now())
})

So the page tells you sub-minute scheduling is impossible, then demonstrates it.

Which one is correct

The second field is real; :39 is the stale sentence. In pkg/gofr/cron.go:

• NewCron ticks once per second — ticker: time.NewTicker(time.Second) (cron.go:73) — so the scheduler is evaluated at second granularity, not minute.
• Both schedule lengths are supported constants: scheduleParts = 5 and schedulePartsWithSecond = 6 (cron.go:22-23).
• job carries a sec field alongside min/hour/… (cron.go:51), and seconds = 59 bounds it (cron.go:17).

:39 looks like it predates the second field and was never removed when that field was added.

Expected behavior

:39 should say the minimum gap is one second when the optional leading second field is used, and one minute with the 5-field form (where second defaults such that the job fires once per minute). Suggested replacement:

With the 5-field format the minimum time difference between a cron job's two consecutive runs is a minute, since minute is then the least significant scheduling parameter. Adding the optional leading second field lowers that to a second — GoFr's scheduler ticks every second.

More description

Pre-existing and unrelated to any in-flight change; surfaced during review of #3815, which touched docs/guides/graceful-shutdown/page.md and deliberately left this out of scope. Docs-only — no code change is implied, since the code already behaves as the second field documents.

[adarshjnv9100]

Hi @akshat-kumar-singhal,

I’d like to work on this issue. I’ve reviewed the description and the relevant cron implementation, and I understand that this is a documentation inconsistency rather than a code bug.

My planned workflow is:

1. Verify the current cron implementation

   • Review pkg/gofr/cron.go.
   • Confirm that the scheduler evaluates jobs every second using time.NewTicker(time.Second).
   • Verify that both 5-field and 6-field cron expressions are supported through scheduleParts and schedulePartsWithSecond.
   • Confirm that the job structure supports the optional sec field.

2. Review the documentation

   • Inspect docs/advanced-guide/using-cron/page.md.
   • Locate the statement claiming that the minimum interval between consecutive cron runs is one minute.
   • Compare it with the documentation describing the optional second field and the existing */10 * * * * * example.

3. Correct the contradictory statement

   • Update the documentation so that it clearly explains:

     • The 5-field format has a minimum interval of one minute.
     • The optional 6th/leading second field allows scheduling at second-level granularity.
     • GoFr's cron scheduler evaluates schedules every second.

4. Keep the change documentation-only

   • No changes to pkg/gofr/cron.go should be necessary because the implementation already supports second-level scheduling.
   • Keep the wording consistent with the existing cron syntax and examples.

5. Validate the documentation

   • Check the surrounding cron examples to ensure there are no other contradictory statements.
   • Verify that the updated explanation matches the actual implementation.
   • Run the relevant documentation checks/build if available.

6. Submit a focused PR

   • Make only the necessary documentation changes.
   • Reference #3876 in the PR.
   • Clearly mention that the PR resolves the contradiction between the minimum-interval statement and the documented second field.

The proposed wording in the issue makes sense to me, with the key clarification being that the 5-field format is minute-granularity while the optional 6-field format supports second-granularity scheduling.

I’d be happy to take this up. Please assign the issue to me. Thanks!