# PODNAME: Statocles::Help::Upgrading
# ABSTRACT: A guide to pitfalls when upgrading Statocles

=head1 DESCRIPTION

This document describes deprecated features and other pitfalls to encounter
when upgrading Statocles.

=head1 DEPRECATIONS

=head2 v0

=over 4

=item site "index" property should be absolute path to index page (got "%s")

The L<site object|Statocles::Site> "index" property used to be the name of the
application that should be used as the index. For this to work, applications
need to say which of their pages should be the site index, which they did by
putting that page first in the list of pages returned. This was magic, and
prone to breakage. It also doesn't allow the site author to choose any page
they want as the site index.

To fix this, set the site's "index" property to the path to the page you want
to be the index page, including the leading slash.

See the L<docs for the index property of the Site object|Statocles::Site/index>
for more information.

Deprecated in v0.051. Fatal in v1.000. Exception removed in v2.000.

Thanks to L<Kyle Sheely|https://github.com/kylesheely> for the idea.

=item Statocles::Store::File is deprecated

Statocles::Store::File was created in anticipation of making other Store
objects like MongoDB or Hadoop. But, having it merely complicates the API
without actually changing whether other Stores could be created (apparently I
forgot that polymorphism exists).

Since the likelihood of those other Stores is low, and since having only one
Statocles::Store doesn't prevent making a Statocles::Store::MongoDB or
Statocles::Store::Custom class, it's better to remove this complexity before
v1.000

The shim module that remains in place will be removed in v1.000.

=item Statocles::Store->write_document returning a value is deprecated

The C<write_document> method for L<Statocles::Store|Statocles::Store> used to
return the full path to the document written. This was for display purposes
only, as developers should be using the store object to deal with the
filesystem. It was thought that this would provide encapsulation, but that was
misguided at best.

With Statocles::Store::File removed, there's no need for a write method to
return anything. Now, C<write_document> and C<write_file> work the same.

This method was removed in C<0.100>.

=item Statocles::App::Plain has been renamed to Statocles::App::Basic

The name "Plain" did not really explain well what the app was. The name "Basic"
implies that it is the base functionality for Statocles apps.

Simply switching your existing Plain apps to Basic apps will solve this problem
with no change to functionality.

The Plain app stub will be removed in v2.000.

=item Statocles::App::Static has been replaced by Statocles::App::Basic

Since every application now has the ability to copy static files, there's no
real reason to have an app specifically for static files. To host static files
without bells and whistles, the Basic app can be used.

The Static app will be removed in v2.000.

=item The tzoffset shim method will be removed in Statocles version 2.0.

In order to allow documents dated before 1900, Statocles is now using
a different date/time library, L<DateTime::Moonpig>. This new library
is mostly compatible, except for the the C<tzoffset> method, which is
used by the RSS feed because it uses the RFC822 date format.

Statocles adds a shim method that replicates the functionality, but it
is a better idea to fix your templates to use the correct method.

To fix this, copy the C<blog/index.rss.ep> template from the default
theme, or change C<$p-E<gt>date-E<gt>tzoffset / 36> in the C<pubDate>
tag to C<$p-E<gt>date-E<gt>offset / 3600>.

Deprecated in v0.070. Will be removed in v2.000.

=item Invalid data attribute in document

As the first place we added the C<data> attribute,
L<Statocles::Document> objects always allowed any kind of data to be put
there. Later, when we added C<data> attributes to the site, theme, app,
and page objects, we only allowed hashes.

To make things consistent, and since allowing arrays and plain strings
as the data doesn't really gain anything.

To fix this, make your string or array a key in your data hash:

    # old
    ---
    data:
        - 1
        - 2
        - 3

    # new
    ---
    data:
        numbers:
            - 1
            - 2
            - 3

    # old
    ---
    data: foo

    # new
    ---
    data:
        variable_name: foo

Deprecated in v0.075. Will be removed in v2.000.

=item Using default layout "site/layout.html.ep" is deprecated

The old default layout was located in the C<site> directory of the
theme. This worked when there was only one default layout, but now there
are multiple. So, the layouts were moved to their own directory:
C<layout>. The default layout is now C<layout/default.html.ep>.

To fix this, either move your current C<site/layout.html.ep> to
C<layout/default.html.ep>, or explicitly override the default layout in
your site config:

    site:
        args:
            # ...
            templates:
                layout.html: site/layout.html

Deprecated in v0.75. Will be removed in v2.000.

=back

=head1 BREAKING CHANGES

=head2 v0.055

=over 4

=item Perldoc application paths have changed

The L<Perldoc app|Statocles::App::Perldoc> now creates directories so that
documentation paths no longer need a C<.html> at the end.

    /pod/Statocles/App.html -> /pod/Statocles/App

The documentation page path now ends with C</index.html>, and the source
page is in the same directory and named C</source.html>.

This change was made to make the URLs look nicer, but also to hopefully allow
for extra documentation collateral in the future, like images and diagrams.

=back

=head1 SEE ALSO

=over 4

=item *

L<Statocles::Help::Policy> - Policy for deprecations

=back