ISO8601DateFormatter

[dpfannenstiel]

As a web site developer I want to support time zone within my posts without having to write a custom date formatter. The default date formatter has support for the format "yyyy-MM-dd HH:mm", which ignores time zone.

In Publish 0.5.0 date formatting is handled via the DateFormatter class, which conforms to the Formatter protocol. Along with the many fine date formats there exists ISO 8601, which the Foundation framework implements in the ISO8601DateFormatter class, which also conforms to the Formatter protocol. Since PublishingContext requires a DateFormatter I cannot use ISO8601DateFormatter.

This pull request makes two changes.

First, it introduces AnyDateFormatter, a minimal protocol to define a common interface for date formatters to conform. Most of the API is already implemented by DateFormatter and ISO8601DateFormatter, so implementing the protocol as an extension is trivial.

Second, PublishingContext changes dateFormatter to a AnyDateFormatter and then make any subsequent changes to support that type change. As part of this change, the default dateFormatter value is set to a ISO8601DateFormatter. This will result in a breaking change for existing users of Publish, but it is believed that using a well known date format represents a common initial case.

[john-mueller]

I think the addition of AnyDateFormatter and ISO 8601 compatibility make sense. I don't think making it the default is the best option, however, as I think most people would rather use the current default "2020-03-12 15:00", as opposed to "2020-03-12T15:00:00-06:00".

You could use ISO 8601 with a custom step:

.step(named: "Use ISO8601DateFormatter") { context in
    if #available(OSX 10.12, *) {
        context.dateFormatter = ISO8601DateFormatter()
    }
}

It's probably worth adding that to Documentation/HowTo/using-a-custom-date-formatter.md.

[dpfannenstiel]

I've updated the PR with better documentation on AnyDateFormatter.

My thoughts regarding the default date formatter are based around standards. ISO 8601 has really wide adoption, whereas the current default is pretty custom and doesn't handle timezone at all. I don't know what the roadmap to 1.0 looks like, but thinking about onboarding a new user you want to give them the minimum amount of friction to deployment. So I guess it becomes a question of how important is time zone localization to a mature product for deployment.

[JohnSundell]

I think this is a great change, thanks @dpfannenstiel! I added a few comments inline that will need to be addressed before this can be merged in, but otherwise I'd be happy to make this a part of Publish's official API 👍

[JohnSundell]

This comment is unnecessary, since the code is completely self-explanatory.

[dpfannenstiel]

Digging into the PR notes I found a (better) version of this protocol exists as part of your Codextended library. The major difference is that this version conforms to Formatter. I'm pretty comfortable dropping that requirement.

I still think that AnyDateFormatter has a valuable place in Publish to support ISO 8601. Including this protocol is redundant. Not including it requires an @import Codextended anyplace we use it, regardless of other comments. I'd like your thoughts.

[JohnSundell]

This API is not used within Publish, so including it feels a bit like premature generalization, and makes the AnyDateFormatter protocol more complex than it has to be.

[JohnSundell]

This API is not used within Publish, so including it feels a bit like premature generalization, and makes the AnyDateFormatter protocol more complex than it has to be.

[addisonwebb]

This is actually used in MarkdownMetadataDecoder here.

[JohnSundell]

This documentation seems to be copied from Apple, which is not allowed. I'd recommend coming up with an original, simpler description of the method.

[JohnSundell]

Please use the same start-of-file header as the rest of the project uses (but with your copyright, of course).

[JohnSundell]

Same thing here, this comment is not required and should be removed.

[JohnSundell]

I think a better solution would be to remove this from the protocol requirements, as recommended above.

[dpfannenstiel]

I had two reasons for including this. Initially because in at least one place Publish reads a dateFormat out of a AnyDateFormatter.
The second reason is that from an API design perspective what AnyDateFormatter is doing is defining the minimum standard interface for a date formatter. A data formatter without read access to a date format didn't make sense to me. If anything ISO8601DateFormatter represented a special case that needed to be handled. This way instead of having to special case date formatter every time we need the dateFormat we now know the property is available.

[JohnSundell]

Please remove this whitespace.

[addisonwebb]

This is something I would love to have merged. Is there any way I can help out with this @dpfannenstiel?

[dpfannenstiel]

@addisonwebb I’m trying to get @JohnSundell thoughts on how to include the AnyDateFormatter. Digging around I had found a version of it in a support library. But modifications are required. I’m not a huge fan of duplicating code needlessly and Codextended seems like the place to do it.

[addisonwebb]

Ok @dpfannenstiel @JohnSundell I have submitted 2 PRs to address this issue using the existing AnyDateFormatter in Codextended.

• Codextended PR #15
• Publish PR #109

These should be the minimal changes necessary to allow Publish users to use both DateFormatter and ISO8601DateFormatter as the custom date formatter on the publishing context. No breaking changes are introduced by these changes.