Release notes for 1.0 (#514)

docs/releases/index.rst

@@ -12,16 +12,10 @@ Wagtail CRX (previously CodeRed CMS) follows the
 * **Patch** - guaranteed to be backwards compatible. These changes are
   reserved for bug, security, or documentation fixes only.
 
-.. note::
-
-   There may be breaking changes between minor version upgrades until reaching a
-   stable 1.0 status. Releases with a zero major version number are considered
-   "beta" quality.
-
-
 .. toctree::
     :maxdepth: 1
 
+    v1.0.0
     v0.25.2
     v0.25.1
     v0.25.0

docs/releases/v1.0.0.rst

@@ -0,0 +1,212 @@
+v1.0.0 release notes
+====================
+
+Today we celebrate our 43rd public release of CRX! This is the largest release
+ever with tons of performance improvements that will increase the speed and
+accessibility of your CRX website.
+
+
+New features
+------------
+
+* Upgrade to Wagtail 3.
+
+* Upgrade to Bootstrap 5 (ships with Bootstrap 5.2).
+
+* Removed jQuery, modernizr, and many other JavaScript improvements.
+
+* Use WebP image format. If you need to support older browsers released prior to
+  2020, disable this feature. See :doc:`/how_to/images`.
+
+* New Accordion snippet and block. See :doc:`/features/snippets/accordions`.
+
+* Added hidden "skip navigation" link for accessibility.
+
+* Most settings have been consolidated in the Wagtail admin under
+  **Settings > CRX Settings**
+
+* Codebase has been formatted with ``black`` to improve readability and
+  maintainability.
+
+* CRX 1, Wagtail 3, and Bootstrap 5 all drop support for Internet Explorer. If
+  you need to support Internet Explorer, follow the Bootstrap 4 guide below.
+
+
+Upgrade instructions
+--------------------
+
+.. important::
+
+   It is highly recommended to first upgrade and deploy your site in production
+   with version 0.25 before performing the upgrade to 1.0.
+
+Updating Python code
+''''''''''''''''''''
+
+#. Run ``pip install coderedcms==1.0.*`` and update your ``requirements.txt``
+   with ``coderedcms==1.0.*``.
+
+#. Follow the `Wagtail 3 upgrade instructions
+   <https://docs.wagtail.org/en/stable/releases/3.0.html#upgrade-considerations-changes-affecting-all-projects>`_.
+   This primarily involes running the following tool to update the Wagtail
+   imports:
+
+   .. code-block:: text
+
+      wagtail updatemodulepaths
+
+#. Find and replace the following panels in your Python code:
+
+   * ``StreamFieldPanel``
+   * ``RichTextFieldPanel``
+   * ``ImageChooserPanel``
+   * ``DocumentChooserPanel``
+   * ``SnippetChooserPanel``
+
+   with:
+
+   * ``FieldPanel``
+
+#. Find all instances of ``StreamField(`` and add the ``use_json_field=True``
+   argument.
+
+#. Rename ``BASE_URL`` to ``WAGTAILADMIN_BASE_URL`` in your Django settings.
+
+#. Find and delete any references to ``ADASettings`` in your Python and HTML
+   code.
+
+#. Find and replace the following references in both Python and HTML code:
+
+   * ``GeneralSettings``
+   * ``GoogleApiSettings``
+   * ``MailchimpApiSettings``
+
+   with:
+
+   * ``LayoutSettings``
+
+#. Make and run migrations:
+
+   .. code-block:: text
+
+      python manage.py makemigrations
+      python manage.py migrate
+
+#. Next, choose whether to upgrade to Bootstrap 5, or stay on Bootstrap 4.
+
+If upgrading your site to Bootstrap 5
+'''''''''''''''''''''''''''''''''''''
+
+#. Add ``django_bootstrap5`` to ``INSTALLED_APPS``..
+
+#. If you are not using ``django-bootstrap4`` elsewhere in your project, remove
+   ``bootstrap4`` from ``INSTALLED_APPS``.
+
+#. In your Django settings file, remove the ``BOOTSTRAP4`` dictionary.
+
+#. Update your HTML templates to `Bootstrap 5.2 <https://getbootstrap.com/>`_.
+   Compare your custom templates to the stock ones for help:
+   https://github.com/coderedcorp/coderedcms/tree/dev/coderedcms/templates.
+
+#. Notable template changes:
+
+   * ``event_index_page.html`` and ``calendar.html`` have changed.
+
+   * ``location_index_page.html`` has changed.
+
+   * ``stream_form_page.html`` has changed.
+
+   * ``form_page.html`` and ``pagepreview_form.html`` have changed to use
+     ``django_bootstrap5`` rendering.
+
+   * ``article_index_page.html`` and ``article_page.html`` have a new design
+     that is closer to stock Bootstrap.
+
+   * ``grid_block.html`` now has with a CSS class ``crx-grid`` which
+     adds padding to the top and bottom. This can be disabled in sass builds, or
+     overridden with CSS or in the template.
+
+   * Blocks no longer render with a ``<div class="block-*">`` wrapper. This may
+     affect custom CSS.
+
+#. ``pages/base.html`` template has removed ``{% block required_scripts %}``.
+   Delete it from your template if it is present.
+
+#. If you still rely on jQuery, be sure to add it to your base template in
+   ``{% block custom_scripts %}``. Generally speaking, any instance of the
+   ``custom_scripts`` block should call ``block.super`` to preserve scripts from
+   parent templates as such:
+
+   .. code-block:: django
+
+      {% block custom_scripts %}
+      {{ block.super }}
+      <script src="my-script-here.js"></script>
+      {% endblock %}
+
+#. All CSS class names and JavaScript files beginning with ``codered-`` have
+   been renamed to ``crx-``. Find and replace those in your templates and CSS.
+
+#. The new templates all use WebP images. See: :doc:`/how_to/images` for options
+   to disable this if needed.
+
+#. If you are using Sass, update your ``_variables.scss`` and ``custom.scss``
+   files appropriately. As a starting point, update your Sass files to match our
+   project template:
+   https://github.com/coderedcorp/coderedcms/tree/dev/coderedcms/project_template/sass/website/static/website/src.
+
+If staying on Bootstrap 4
+'''''''''''''''''''''''''
+
+While we recommend *eventually* upgrading to Bootstrap 5, for larger sites or
+highly customized sites, this can be a lengthy process. We have published a
+`compatibility theme <https://github.com/coderedcorp/coderedcms-bootstrap4>`_
+which preserves all the old Bootstrap 4 templates, CSS, Sass, and JavaScript.
+
+Do not follow any of the steps above in the Bootstrap 5 section if you are
+staying on Bootstrap 4!
+
+#. Run ``pip install coderedcms-bootstrap4`` and add to your
+   ``requirements.txt`` file ``coderedcms-bootstrap4==1.*``.
+
+#. In your Django settings file, add ``coderedcms_bootstrap4`` **ABOVE** the
+   ``coderedcms`` app:
+
+   .. code-block:: python
+
+      INSTALLED_APPS = [
+          ...,
+          "coderedcms_bootstrap4",
+          "coderedcms",
+          ...,
+      ]
+
+Final steps: after deploying
+''''''''''''''''''''''''''''
+
+Locally in development, and after deploying your upgraded site to production,
+you should run the following commands to clean up the site.
+
+Run migrations (as usual):
+
+.. code-block:: text
+
+   python manage.py migrate
+
+Delete old media renditions:
+
+.. code-block:: text
+
+   python manage.py wagtail_update_image_renditions --purge-only
+
+Update Wagtail search index:
+
+.. code-block:: text
+
+   python manage.py wagtail_update_index
+
+
+Thank you!
+----------
+
+Thanks to everyone who contributed to `1.0.0 on GitHub <https://github.com/coderedcorp/coderedcms/milestone/1?closed=1>`_.