From 9b91b248ab9ec1efac57c64db48cb357293ec344 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 2 Mar 2017 12:48:31 -0500 Subject: [PATCH 1/2] Release :gem: 3.4.1 --- History.markdown | 4 ++++ docs/_docs/history.md | 6 ++++++ docs/latest_version.txt | 2 +- lib/jekyll/version.rb | 2 +- 4 files changed, 12 insertions(+), 2 deletions(-) diff --git a/History.markdown b/History.markdown index f3a55f68..66a2236d 100644 --- a/History.markdown +++ b/History.markdown @@ -37,6 +37,10 @@ * Convertible#validate_permalink!: ensure the return value of data["permalink"] is a string before asking if it is empty (#5878) * Allow abbreviated post dates (#5920) +## 3.4.1 / 2017-03-02 + + * Backport #5920 for v3.4.x: Allow abbreviated post dates (#5924) + ## 3.4.0 / 2017-01-27 ### Minor Enhancements diff --git a/docs/_docs/history.md b/docs/_docs/history.md index 7d96660a..acc7e1cf 100644 --- a/docs/_docs/history.md +++ b/docs/_docs/history.md @@ -4,6 +4,12 @@ permalink: "/docs/history/" note: This file is autogenerated. Edit /History.markdown instead. --- +## 3.4.1 / 2017-03-02 +{: #v3-4-1} + +- Backport [#5920]({{ site.repository }}/issues/5920) for v3.4.x: Allow abbreviated post dates ([#5924]({{ site.repository }}/issues/5924)) + + ## 3.4.0 / 2017-01-27 {: #v3-4-0} diff --git a/docs/latest_version.txt b/docs/latest_version.txt index 18091983..47b322c9 100644 --- a/docs/latest_version.txt +++ b/docs/latest_version.txt @@ -1 +1 @@ -3.4.0 +3.4.1 diff --git a/lib/jekyll/version.rb b/lib/jekyll/version.rb index 4babc208..20060c51 100644 --- a/lib/jekyll/version.rb +++ b/lib/jekyll/version.rb @@ -1,3 +1,3 @@ module Jekyll - VERSION = "3.4.0".freeze + VERSION = "3.4.1".freeze end From 7b9e64af854e4e891a07979f8e613e8c604ebef0 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 3 Mar 2017 12:09:15 -0500 Subject: [PATCH 2/2] Release post for v3.4.1 --- .../2017-03-02-jekyll-3-4-1-released.markdown | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/_posts/2017-03-02-jekyll-3-4-1-released.markdown diff --git a/docs/_posts/2017-03-02-jekyll-3-4-1-released.markdown b/docs/_posts/2017-03-02-jekyll-3-4-1-released.markdown new file mode 100644 index 00000000..c90e7cfb --- /dev/null +++ b/docs/_posts/2017-03-02-jekyll-3-4-1-released.markdown @@ -0,0 +1,106 @@ +--- +title: 'Jekyll 3.4.1, or "Unintended Consequences"' +date: 2017-03-02 14:20:26 -0500 +author: parkr +version: 3.4.1 +categories: [release] +--- + +Conformity is a confounding thing. + +We write tests to ensure that a piece of functionality that works today +will work tomorrow, as further modifications are made to the codebase. This +is a principle of modern software development: every change must have a +test to guard against regressions to the functionality implemented by that +change. + +And yet, occasionally, our very best efforts to test functionality will be +thwarted. This is because of how our code produces unintended +functionality, which naturally goes untested. + +In our documentation, we tell users to name their posts with the following +format: + +```text +YYYY-MM-DD-title.extension +``` + +That format specifies exactly four numbers for the year, e.g. 2017, two +letters for the month, e.g. 03, and two letters for the day, e.g. 02. To +match this, we had the following regular expression: + +```ruby +%r!^(?:.+/)*(\d+-\d+-\d+)-(.*)(\.[^.]+)$! +``` + +You might already see the punchline. While our documentation specifies the +exact number of numbers that is required for each section of the date, our +regular expression does not enforce this precision. What happens if a user +doesn't conform to our documentation? + +We recently [received a bug report](https://github.com/jekyll/jekyll/issues/5603) +that detailed how the following file was considered a post: + +```text +84093135-42842323-42000001-b890-136270f7e5f1.md +``` + +Of course! It matches the above regular expression, but doesn't satisfy +other requirements about those numbers being a valid date (unless you're +living in a world that has 43 million months, and 42 million (and one) +days). So, we [modified the regular expression to match our +documentation](https://github.com/jekyll/jekyll/pull/5609): + +```ruby +%r!^(?:.+/)*(\d{4}-\d{2}-\d{2})-(.*)(\.[^.]+)$! +``` + +Our tests all passed and we were properly excluding this crazy date with 43 +million months and days. This change shipped in Jekyll v3.4.0 and all was +well. + +Well, not so much. + +A very common way to specify the month of February is `2`. This is true for +all single-digit months and days of the month. Notice anything about our +first regular expression versus our second? The second regular expression +imposes a **minimum**, as well as maximum, number of digits. This change +made Jekyll ignore dates with single-digit days and months. + +The first eight years of Jekyll's existence had allowed single-digit days +and months due to an imprecise regular expression. For some people, their +entire blog was missing, and there were no errors that told them why. + +After receiving a few bug reports, it became clear what had happened. +Unintended functionality of the last eight years had been broken. Thus, +v3.4.0 was broken for a non-negligible number of sites. With a test site +in-hand from @andrewbanchich, I tracked it down to this regular expression +and [reintroduced](https://github.com/jekyll/jekyll/pull/5920) a proper +minimum number of digits for each segment: + +```ruby +%r!^(?:.+/)*(\d{2,4}-\d{1,2}-\d{1,2})-(.*)(\.[^.]+)$! +``` + +And, I wrote a test. + +This change was quickly backported to v3.4.0 and here we are: releasing +v3.4.1. It will fix the problem for all users who were using single-digit +months and days. + +With this, I encourage all of you to look at your code for *unintended* +functionality and make a judgement call: if it's allowed, *should it be*? +If it should be allowed, make it *intended* functionality and test it! I +know I'll be looking at my code with much greater scrutiny going forward, +looking for unintended consequences. + +Many thanks to our Jekyll affinity team captains who helped out, including +@pathawks, @pnn, and @DirtyF. Thanks, too, to @ashmaroli for reviewing my +change with an eye for consistency and precision. This was certainly a team +effort. + +We hope Jekyll v3.4.1 brings your variable-digit dates back to their +previous glory. We certainly won't let that unintended functionality be +unintended any longer. + +As always, Happy Jekylling!