282905 - Add description of relative dates to docs

Status: RESOLVED DUPLICATE of bug 1557186

(Bugzilla :: Documentation, defect)

Description

[Joel Peshkin]

Since even the devlopment team has to look at the source to remember how to use
relative dates in the boolean charts, we should add this to the docs.

In general, anything that could have taken a date value can also take a relative
measure of time.  

-3d or 3d or -3D or 3D would all refer to midnight 3 days ago.
+3d or +3D would refer to midnight 3 days from now.

similarly, weeks are 7 days, but bugzilla does not push weeks to Monday the way
it pushes days to midnight.

-1m or -1M or 1m or 1M would all refer to the first of last month. 0m would be
the start of this month, +1m would be the start of next month

+1y would be the start of next year

Comment 1

[Steve Chapel]

Attachment: A document describing relative date syntax

This document is designed to be linked to the text "relative dates" in the Bug
Changes box on the Advanced Bugzilla Search page at
<https://bugzilla.mozilla.org/query.cgi?format=advanced>

Comment 2

[Steve Chapel]

I just noticed this: Click on the "Give me some help" link at the top of the
page, and mouse over the fields where you can type in relative dates. The popup
gives enough help that we don't need to look at the code or come to this bug
report to figure out the syntax.

Comment 3

[Shane H. W. Travis]

Comment on attachment 177613 [details]
A document describing relative date syntax

steven:  I really like what you've done here, both in terms of content and
style. This is a great start, and will be a lot of help to a lot of people once
we get it in.

Unfortunately, I have to r- it in its present state. The way you've handled it
isn't really 'documentation', as you're adding code to the search page to give
additional information. There is absolutely nothing *wrong* with that approach,
but if that's how you want to attack it, then we need a patch with a 'diff -u'
against existing sources; also, you'll need to find all the relevant places
that would link to this page and add the URL yourself.

If you want to attack it as a documentation bug, then I can either pick up from
where you've left off and use the information you've provided, or I can walk
you through getting that done too.

I'd love to see this information get in *somewhere*... the only issue is where
and how. Please follow up with your intentions.


(In reply to comment #2)
> I just noticed this: Click on the "Give me some help" link at the 
> top of the page...

Am I missing something? I cannot find this link anywhere on bmo, on my clean
tip installation, or on my modified 2.18 installation... but I'm sure I've seen
it. Did we remove it somewhere along the way?

Comment 4

[Colin Ogilvie [:cso]]

(In reply to comment #3)
> (In reply to comment #2)
> > I just noticed this: Click on the "Give me some help" link at the 
> > top of the page...
> 
> Am I missing something? I cannot find this link anywhere on bmo, on my clean
> tip installation, or on my modified 2.18 installation... but I'm sure I've seen
> it. Did we remove it somewhere along the way?

Its there for me on https://bugzilla.mozilla.org/query.cgi?format=advanced - it
links to https://bugzilla.mozilla.org/query.cgi?help=1&format=advanced

Comment 5

[bigstijn]

(In reply to comment #3)
> (From update of attachment 177613 [details] [edit])

> If you want to attack it as a documentation bug, then I can either pick up from
> where you've left off and use the information you've provided, or I can walk
> you through getting that done too.

I think we should attack this (also) as a documentation bug.
Should this be part of section http://www.bugzilla.org/docs/tip/html/query.html ?
But what when bug 324535 is resolved ?
I think it would be a good idea to have the details of such used features in a sort of encyclopaedic list at the end of the documentation.

Anyhow, having it documented somewhere should be great. 

Comment 6

[bigstijn]

Feature of bug 291209 should also be included.
+ Features of bug 313726, if implemented.

Comment 7

[timeless]

Attachment: approximate conversion

I'm assuming dates are relative to server localtime(zone)?

Comment 8

[bigstijn]

(In reply to comment #7)
> Created an attachment (id=275279) [details]
"you can search for things"
Maybe this could be replaced by
"you can search for %bugs%" (or what is the variable name for bugs ).

Comment 9

[Colin Ogilvie [:cso]]

Comment on attachment 275279 [details] [diff] [review]
approximate conversion

>Index: docs/xml/using.xml

>+    <section id="relative-dates">
>+      <title>Relative Dates</title>
>+      <para>
>+        In addition to searching for specific dates, you can
>+        search for things using <quote>relative dates</quote>, i.e. a date
>+        relative to the current date.
>+      </para>

things -> bugs - since the page it's on is headed 'Searching for Bugs' 

>+      <para>
>+        The general format for a relative date is:
>+        <emphasis>sign</emphasis> number <emphasis>unit</emphasis>
>+      </para>

Maybe wrap the "sign number unit" section in a <literal></literal>

>+      <para>
>+        The sign can be "+" for dates in the future, or "-" for dates in the past.
>+        If the sign is omitted, it is assumed to be - for in the past.
>+      </para>

Should quote the second instance of - too, I think.


>+      <para>
>+        The unit can be "d" for days, "w" for weeks, "m" for months, or "y" for years,
>+        and may be lowercase or uppercase.
>+      </para>

I wonder if it would be either more useful to show this in a table:

d - Days
w - Weeks
m - Months
y - Years

or to make the units bold so <b>d</b>, <b>w</b> etc. To me they get lost in the sentence.

>+      <para>
>+        The relative date Now means the current time.
>+      </para>

Quote "Now". Is "Now" case insensitive as well?


>+      <section>
>+        <title>Example Dates</title>
>+        <itemizedlist>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                Relative Date
>+              </emphasis>:
>+              Meaning
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                -30d
>+              </emphasis>:
>+              30 days ago
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                30D
>+              </emphasis>:
>+              30 days ago
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                +30d
>+              </emphasis>:
>+              30 days from now
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                0d
>+              </emphasis>:
>+              00:00 (server local time) today
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                -4w
>+              </emphasis>:
>+              4 weeks ago (28 days ago)
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                -1m
>+              </emphasis>:
>+              The first day of last month
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                0M
>+              </emphasis>:
>+              The first day of this month
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                +1M
>+              </emphasis>:
>+              The first day of next month
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                0y
>+              </emphasis>:
>+              The first day of this year
>+            </para>
>+          </listitem>
>+          <listitem>
>+            <para>
>+              <emphasis>
>+                Now
>+              </emphasis>:
>+              Now
>+            </para>
>+          </listitem>
>+        </itemlist>
>+      </section>
>+    </section>


Personally, I think this would look better as a table per conventions.xml as it looks a bit weird when generated - http://landfill.mozilla.org/csodocs/lpsolit/query.html#relative-dates


Even if you don't decide to change it to a table, the XML is invalid and doesn't compile. 

Thanks for contributing this, Frederic.

Comment 10

[Colin Ogilvie [:cso]]

(In reply to comment #9)

> Thanks for contributing this, Frederic.


Or even timeless. 

Must not rely on the person asking for review to be the patch author...

Comment 11

[Frédéric Buclin]

(In reply to comment #10)
> Must not rely on the person asking for review to be the patch author...

Indeed. I have nothing to do with this patch.

Comment 12

[Kohei Yoshino [:kohei]]

The doc has been added to BMO. It will be shipping with Bugzilla 6.0.