Merge pull request #4485 from jekyll/parkr-future-dates

Add note about dates without timezones

site/_docs/upgrading/2-to-3.md

@@ -105,5 +105,22 @@ relative_permalinks: true
 
 In Jekyll 2, any URL constructed from the `permalink:` field had a trailing slash (`/`) added to it automatically.  Jekyll 3 no longer adds a trailing slash automatically to `permalink:` URLs. This can potentially result in old links to pages returning a 404 error. For example, suppose a page previously contained the YAML `permalink: /:year-:month-:day-:title` that resulted in the URL `example.com/2016-02-01-test/` (notice the trailing slash), Jekyll internaly generates a folder named `2016-02-01-test`. In Jekyll 3, the same `permalink:` generate the file `2016-02-01-test.html` and the URL for the same page will be `example.com/2016-02-01-test`, and consequently any links to the old URL will result in a 404 error. In order to maintain the same URLs and avoid this problem, a trailing slash should be added to the `permalink:` field, for example `permalink: /:year-:month-:day-:title/`. 
 
+### All my posts are gone! Where'd they go!
+
+Try adding `future: true` to your `_config.yml` file. Are they showing up now? If they are, then you were ensnared by an issue with the way Ruby parses times. Each of your posts is being read in a different timezone than you might expect and, when compared to the computer's current time, is "in the future." The fix for this is to add [a timezone offset](https://en.wikipedia.org/wiki/List_of_UTC_time_offsets) to each post (and make sure you remove `future: true` from your `_config.yml` file). If you're writing from California, for example, you would change this:
+
+```yaml
+---
+date: 2016-02-06 19:32:10
+---
+```
+
+to this (note the offset):
+
+```yaml
+---
+date: 2016-02-06 19:32:10 -0800
+---
+```
 
 _Did we miss something? Please click "Improve this page" above and add a section. Thanks!_