New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[JENKINS-9283,JENKINS-38612] - Document timezone support in help pages #1720

Closed
wants to merge 3 commits into
base: master
from

Conversation

4 participants
@oleg-nenashev
Copy link
Member

oleg-nenashev commented May 27, 2015

Follow up to #1672 ...

Added a documentation for the timezones support in CRON.

@0bp @orrc @daniel-beck

<li>The plugin supports all timezones returned by
<a href="https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html#getAvailableIDs()">
java.util.TimeZone::getAvailableIDs()
</a> on the Jenkins server JVM

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

Why not provide a list? Just requires converting the help into a jelly file.

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

Jenkins server is Jenkins master, or what do you mean?

This comment has been minimized.

@oleg-nenashev

oleg-nenashev May 27, 2015

Author Member

Yes, Jenkins master.

Why not provide a list? Just requires converting the help into a jelly file.

I have not found any document describing the guaranteed contents. If I understand correctly, it's up to the JVM and underlying OS

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

Yes, and jelly-based help files could generate the list of available time zones dynamically.

This comment has been minimized.

@orrc

orrc May 27, 2015

Member

Running println java.util.TimeZone.getAvailableIDs() in the Script Console returns 617 timezone IDs (which is 9kB of text, without markup). 12 of which are in Antarctica, and 30 are basically GMT-1, GMT-0, GMT+1, GMT+2 ... — printing it all seems like overkill for inline help text.

I think the examples and patterns below are good, plus there could be a link to the standard tzdb list at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones (or a link to that list on the Jenkins wiki).

This comment has been minimized.

@oleg-nenashev

oleg-nenashev May 29, 2015

Author Member

Agreed, I'll provide a link to the Wiki page. Wikipedia should be OK for such purpose

This comment has been minimized.

@daniel-beck

daniel-beck Jun 2, 2015

Member

@orrc Ouch. Yeah, that would be overkill. Should be enough to have form validation for these names.

@@ -78,4 +78,31 @@
# once a day on the 1st and 15th of every month except December
H H 1,15 1-11 *
</pre>
<p>
<b>Timezones specification</b>. <br/>
Starting from 1.615 Jenkins supports the specification

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

The version this was added is irrelevant.

<b>Timezones specification</b>. <br/>
Starting from 1.615 Jenkins supports the specification
of different timezones in this field. It allows to natively configure all
periodic operations.

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

I don't understand this sentence.

This comment has been minimized.

@orrc

orrc May 27, 2015

Member

I kind of understand the intent, but it does sound weird.

How about replacing both sentences with:

Periodic tasks are normally executed at the scheduled time in the timezone of the Jenkins master JVM (currently Central European Time). This behaviour can be changed by specifying an alternative timezone here."

"Central European Time" comes from TimeZone.getDefault().getDisplayName(), and I say "currently" because the server timezone may change, e.g. daylight savings.

(This text isn't easy to write!)

This comment has been minimized.

@oleg-nenashev

oleg-nenashev May 29, 2015

Author Member

@orrc
👍 the time should be extracted dynamically BTW, but the text is much better than mine

</a> on the Jenkins server JVM
</li>
<li>Examples: EST, Etc/GMT+5, US/Pacific, America/Indiana/Petersburg, etc.</li>
<li>If the timezone line is specified incorrectly, the default Jenkins instance timezone will be used</li>

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

… which is? If this can be determined programatically, it should be displayed.

# This job needs to be run in the morning, London time
H 8 * * *
# Butlers do not have a five o'clock, so we run the job again
H(0-30) 15 * * *

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

Comment and expression appear to specify different times? Also, not sure what the comment refers to. Leaving work for the day?

<p>
<b>Timezones specification</b>. <br/>
Starting from 1.615 Jenkins supports the specification
of different timezones in this field. It allows to natively configure all

This comment has been minimized.

@daniel-beck

daniel-beck May 27, 2015

Member

"of a time zone" would be clearer as it's only possible to specify one (and it doesn't have to be different from the default).

@@ -78,4 +78,31 @@
# once a day on the 1st and 15th of every month except December
H H 1,15 1-11 *
</pre>
<p>
<b>Timezones specification</b>. <br/>

This comment has been minimized.

@orrc

orrc May 27, 2015

Member

"Timezones" > "Timezone"

periodic operations.

<ul>
<li>Timezone can be specified in the first line, which should contain the &quot;TZ=$(timezoneID)&quot; string</li>

This comment has been minimized.

@orrc

orrc May 27, 2015

Member

I would be a bit more explicit that it must be the first line, and maybe we should avoid hinting at the $(...) syntax, as I don't believe this field can resolve environment variables.

Something like this, perhaps?

<li>The timezone must be specified on the first line of this field, in the format: <tt>TZ=&lt;timezone ID&gt;</tt></li>
<li>All subsequent scheduled times will be interpreted using this timezone</li>

This comment has been minimized.

@daniel-beck

daniel-beck Jun 2, 2015

Member

@orrc Needs to prevent the impression that specifying TZ is mandatory.

This comment has been minimized.

@orrc

orrc Jun 2, 2015

Member

@daniel-beck I think that's covered by "This behaviour can be changed" above.

But the first line here could also be changed to "If a timezone is specified, it must be on the first line of this field, in the format..."


<ul>
<li>Timezone can be specified in the first line, which should contain the &quot;TZ=$(timezoneID)&quot; string</li>
<li>The plugin supports all timezones returned by

This comment has been minimized.

@orrc

orrc May 27, 2015

Member

Plugin? :)

@oleg-nenashev oleg-nenashev changed the title [JENKINS-9283] - Document timezones support in help pages [WiP] [JENKINS-9283] - Document timezones support in help pages May 29, 2015

@oleg-nenashev

This comment has been minimized.

Copy link
Member Author

oleg-nenashev commented May 29, 2015

Thanks for the comments. This attempt was not good, I'll rework docs

@oleg-nenashev oleg-nenashev force-pushed the oleg-nenashev:JENKINS-9283-docs branch from d79d7ab to 9d9b21e Jun 6, 2015

@oleg-nenashev

This comment has been minimized.

Copy link
Member Author

oleg-nenashev commented Jun 6, 2015

@daniel-beck @orrc
Sorry for the delay. I've fixed the helpfile comments and added the form validation

@daniel-beck

This comment has been minimized.

Copy link
Member

daniel-beck commented Jun 11, 2015

@oleg-nenashev Do you still consider this to be a work in progress?

@oleg-nenashev oleg-nenashev changed the title [WiP] [JENKINS-9283] - Document timezones support in help pages [JENKINS-9283] - Document timezones support in help pages Jun 11, 2015

@oleg-nenashev

This comment has been minimized.

Copy link
Member Author

oleg-nenashev commented Jun 11, 2015

@daniel-beck
No, I'm waiting for the review. Sorry for the PR title

<p>
<b>Timezone specification</b>. <br/>
Periodic tasks are normally executed at the scheduled time in the timezone of
the Jenkins master JVM (currently Central European Time).

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

Huh? All Jenkins masters are in CET?

This comment has been minimized.

@oleg-nenashev

oleg-nenashev Jun 13, 2015

Author Member

Sorry, it was a baindead copy-paste from @orrc 's proposal

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

I still think a Jelly based help file could at least show the current time zone.

first line of the field.
</p>
<ul>
<li>Timezone specification should contain the &quot;TZ=$(timezoneID)&quot; string</li>

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

should looks like a soft recommendation, when it fact it's a hard requirement. Otherwise it's not a TZ specification. Also, it does not contain this string, this is what the entire thing looks like.

<ul>
<li>Timezone specification should contain the &quot;TZ=$(timezoneID)&quot; string</li>
<li>If a timezone is not specified, the default Jenkins JVM timezone will be used</li>
<li>Th supports all timezones returned by

This comment has been minimized.

@daniel-beck
<li>Th supports all timezones returned by
<a href="https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html#getAvailableIDs()">
java.util.TimeZone::getAvailableIDs()
</a> on the Jenkins server JVM

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

Maybe link to /script ( + rootURL) where users can look for valid TZs?

java.util.TimeZone::getAvailableIDs()
</a> on the Jenkins server JVM
</li>
<li>Examples: EST, Etc/GMT+5, US/Pacific, America/Indiana/Petersburg, etc.</li>

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

Clarify: Examples for timezone IDs

<li>Examples: EST, Etc/GMT+5, US/Pacific, America/Indiana/Petersburg, etc.</li>
</ul>
<p>
Example:

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

Clarify: Complete example of schedule with custom timezone

} else {
LOGGER.log(Level.CONFIG, "invalid timezone {0}", line);
throw new ANTLRException("Invalid or unsupported timezone '" + line + "'");

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

I think it would suffice to only show the timezone ID here (i.e. line.replace("TZ=","")).

<b>Timezone specification</b>. <br/>
Periodic tasks are normally executed at the scheduled time in the timezone of
the Jenkins master JVM (currently Central European Time).
This behaviour can be <b>optionally</b> changed by specifying an alternative timezone in the

This comment has been minimized.

@daniel-beck

daniel-beck Jun 13, 2015

Member

Isn't Jenkins mostly American English? If so, behavior.

@daniel-beck

This comment has been minimized.

Copy link
Member

daniel-beck commented Mar 15, 2016

@oleg-nenashev Was surprised to see this is still undocumented, so if you have some time would be great if this could be finished.

@daniel-beck

This comment has been minimized.

Copy link
Member

daniel-beck commented Apr 25, 2016

@oleg-nenashev Could we please move this along?

@oleg-nenashev

This comment has been minimized.

Copy link
Member Author

oleg-nenashev commented May 5, 2016

@daniel-beck Sorry for the delay. Dropped the ball on it :(

@oleg-nenashev oleg-nenashev changed the title [JENKINS-9283] - Document timezones support in help pages [JENKINS-9283] - Document timezone support in help pages Sep 23, 2016

@oleg-nenashev oleg-nenashev changed the title [JENKINS-9283] - Document timezone support in help pages [JENKINS-9283,JENKINS-38612] - Document timezone support in help pages Oct 3, 2016

@aheritier

This comment has been minimized.

Copy link
Member

aheritier commented Feb 13, 2017

ping

@oleg-nenashev

This comment has been minimized.

Copy link
Member Author

oleg-nenashev commented Feb 13, 2017

@aheritier Work in progress
slowpoke

@daniel-beck

This comment has been minimized.

Copy link
Member

daniel-beck commented Jul 2, 2017

Superseded by #2927

@daniel-beck daniel-beck closed this Jul 2, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment