GHURLBot (original) (raw)

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:

This date format is quite hard to parse (relative to others that may be used).
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:

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.