Standardising on a format/position for due dates in issue comments?

[matatk]

When creating GitHub issues, the bot creates comments of the form "due {day_number} {abbreviated_month_name} {year_number}" in the issue's comment text.

I'm experimenting with some scripts to help our group's members with tracking actions logged in GitHub (which use the GitHub API), and encountered two barriers:

1. This date format is quite hard to parse (relative to others that may be used).

2. The docs for the bot don't specify a canonical place within the comment where the due date can be found.

I have two suggestions. Following either one would solve both problems above, though I'd appreciate your consideration on both.

Thank you for working on this bot; we've just started using it, and the manual has got us excited about what we can do with it :-).

Suggestion: use ISO-format date strings

Many languages provide standard APIs to parse ISO-format dates, but don't support the format that the bot writes. If the bot created issues using ISO date-string format, it would be much easier to both find and parse the due date. I propose that due dates be expressed in comments in the form:

Due: YYYY-MM-DD

Would that be acceptable?

(I suggest "Due: " as the prefix, as it feels neater, but it's not a big deal.)

I understand that including the month name makes it more legible for people, so you might consider something like this, too:

Due: YYYY-MM-DD ({weekday_name} {day_number} {full_month_name})

That would make the date easy for both machines and people to find and parse. It's more verbose, but includes some helpful checksumming info for people.

Suggestion: document exactly where the due date information should be within comments

It would also be helpful to document where in the comment the due date will be written by the bot and, if the comment is edited, where the due date should be in order to get picked up by tooling that is built on top of the GitHub API.

It seems like if the due date were present on—and took up the entirety of—either the first or last line of the comment, that would make it easier to find and parse.

[matatk]

Having worked with the output from the bot for a little while via a tool I'm writing to help us track actions, I have a few updates:

• I've noticed that the date string is always the same length (as the bot pads single-digit day numbers, if needed), and that it complies with the regex ^due ?(\d\d? [[:alpha:]]{3} \d{4})$ and that the date format for the part in parentheses there can be specified quite conventionally as %d %b %Y.

• I still have a preference for the international date format (YYYY-MM-DD), as it feels clearer to me, and would still be a bit less effort to parse, but again, that is just my tuppence [cultural alt=two cents] :-).

• Deciding on, and documenting, a standard location/locations for the date string (i.e. first line only; first-or-last line) would be very helpful. We could look at how people are using action issues to see which should be supported.

[bert-github]

The bot now writes something like

Due: 2023-07-29 (Saturday 29 July)

into the description when it creates an action item.

When reading an action item, it expects that text either at the start or at the end of the description.

More precisely, it expects either:

1. at the start of the description: optional white space, the text due: (case-insensitive), one or more white space characters, and the pattern yyyy-mm-dd (where y, m and d are decimal digits); or
2. at the end of the description: the text due: (case-insensitive), one or more white space characters, the pattern yyyy-mm-dd, optional white space, optional text between parentheses, optional white space, an optional full stop and more optional white space.

(The source code contains the above as a Perl regular expression.)

The bot ignores the date between parentheses (does not even check if it is correct) and only uses the ISO-date. If there is a due date both at the start and at the end, the start wins.

@matatk, does that work for you?

[matatk]

@bert-github that's very clear, and seems good for parsing and people, thanks. I think it'd be a good idea to document this in the README (or somewhere you think apt) if it's not already.

[bert-github]

The format and location of the due date of an action is now documented in manual.html (see commit 99e3a82).

[matatk]

Hi @bert-github. I have a follow-up question on this: the behaviour of the bot has changed since your comment above: the bot can include a line at the start of the body text of the action, e.g.:

Opened by matatk via IRC channel #apa on irc.w3.org

This is followed by a blank line, then the due date. Example issue: w3c/apa#339.

The format section in the manual still talks about anchoring the due date to the start/end of the body, but the "metadata" line isn't mentioned.

Do you intend to keep the current behaviour (where the due date could be on line 3—or in fact any line, if I'm reading the code correctly)? (If yes, please could you update the manual?)

IMHO I like the idea of having the due date on the first line for readability, as it's the most important info for which GitHub doesn't provide a dedicated field, plus parsing would be more efficient if that were the convention.

[bert-github]

The line ‘Opened by…’ is now documented in the manual.

I put that text at the start of the action body, so people do not wonder who ‘gb’ is. The due date thus becomes the end of the body text.

@matatk, would it be better to require that the due date constitutes a single line, rather than require that it occurs at the start or end of the body? I see that your code assumes the former.

[matatk]

Hi @bert-github, thanks for your quick reply, and for updating the manual. I changed my code, to match the bot's behaviour, to allow the due date being on any line. (Apologies for the resulting noise in this thread from my pushes).

I think your idea about specifying that the due date must be on a line of its own (and that it can be on any line) is good—the part about it being on a line of its own would simplify the regexes I'm using, I have just realised, which would help with efficiency a little bit at least :-).

ACK your point about the first line giving some context.

[bert-github]

Gb now expects the due date to be all on one line (with nothing else on the line than possibly some white space and a period); and that line can be anywhere in the body text.

The documentation has been updated.