Role connection metadata datetime types are documented in reverse

[evaera]

Description

The Application Role Connection Metadata Type variants DATETIME_LESS_THAN_OR_EQUAL (5) and DATETIME_GREATER_THAN_OR_EQUAL (6) are documented in reverse from the way that they actually work in practice.

DATETIME_LESS_THAN_OR_EQUAL, which is type ID 5, is documented as such:

the metadata value (ISO8601 string) is less than or equal to the guild's configured value (integer; days before current date)

Our application's join_date field was configured as type ID 5, which is DATETIME_LESS_THAN_OR_EQUAL. The join date is set correctly and displays as you'd expect in the user's locale.

• The "metadata value", as described the docs, is the user's join date.
• The "guild's configured value", as described in the docs, is an integer, which is days before the current date.
• If the "configured value" is 5, then that date is 5 days ago.
• Therefore, the comparison is: join date <= date 5 days ago. Which should be TRUE if the account is older than 5 days.

However, it doesn't work.

As it stands, the current behavior only allows users that joined within the last 5 days, not users whose accounts are older than 5 days.

Flipping our join_date field to type ID 6, which is DATETIME_GREATER_THAN_OR_EQUAL fixes the problem and the requirement works as expected.

So, it appears that these metadata types are flip-flopped in the docs. Dates go up as time moves forward, so join_date LESS THAN configured_date is the correct comparison.

Steps to Reproduce

• Create a role connection metadata field with type ID 5
• Set a datetime for that field on a user in the past (well in the past, like 2015)
• Enable the condition in the linked role, choose something like 5 days ago
• The user cannot opt-in to the linked role, even though the their date is well in the past

Expected Behavior

The docs should be updated to reflect the correct direction of the comparison

Current Behavior

The two variants work in reverse order as they are documented

Screenshots/Videos

No response

Client and System Information

N/A

[panley01]

I think this is an interesting miscommunication on what greater than and less than actually means in this implementation.

To my understanding, and based on behaviour, DATETIME_LESS_THAN_OR_EQUAL equates to a difference between datetimes being less than or equal to the given value (where the datetime provided in the metadata is compared to the current datetime). That makes behaviour consistent with expectations. Based on the description given:

the metadata value (ISO8601 string) is less than or equal to the guild's configured value (integer; days before current date)

This is accurate and consistent behaviour, if you set a requirement of 5 days, the value will only be true if the difference between the current datetime and metadata datetime is less than or equal to 5 days.

I think the docs could potentially make this clearer, I can see why you read this the way you did. I would not count this as a bug and open a PR to add a clarification on the behaviour.

[Mehgugs]

These are named somewhat unfortunately, and again it puzzles me as to why the comparison operator is baked into the metadata.
Nevertheless #5827 is tracking clarity of the documentation; so I think you should mention this ambiguity there

[evaera]

Yes, this issue was opened as a problem with the docs, not necessarily a "bug", though it seems like the issue creation wizard forces the bug tag automatically.

The docs don't mention that the comparison is against the difference between the datetimes. If it did, then the current names make sense. However, the current descriptions of the DATETIME_LESS_THAN_OR_EQUAL and DATETIME_GREATER_THAN_OR_EQUAL variants clearly say "metadata value is less than configured value", which is directly referring to the two dates as the operands of the comparison, not the difference.

It would be enough for the descriptions of the variants to be updated to mention this, the names don't necessarily need to be swapped.