Skip to content

Commit

Permalink
[TASK] Add information on how to render the Changelog (#347)
Browse files Browse the repository at this point in the history 
* [TASK] Add information on how to render the Changelog

So ppl dont need to go looking for it.

* Update Documentation/AddingDocumentation/Index.rst

* Update Documentation/AddingDocumentation/Index.rst

* Update Documentation/AddingDocumentation/Index.rst

* Update Documentation/AddingDocumentation/Index.rst

Co-authored-by: Stefan Frömken <[email protected]>

---------

Co-authored-by: Stefan Frömken <[email protected]>
  • Loading branch information
@linawolf @froemken
linawolf and froemken authored Jul 27, 2024
1 parent ef0d914 commit d357bde
Show file tree
Hide file tree
Showing 2 changed files with 98 additions and 80 deletions.
175 changes: 95 additions & 80 deletions Documentation/AddingDocumentation/Index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,54 +1,81 @@
.. include:: /Includes.rst.txt
.. include:: /Includes.rst.txt

.. index::
single: Documentation Contribution; Adding Documentation
.. index::
single: Documentation Contribution; Adding Documentation

.. _Bugfixing-Adding-documentation:
.. _Adding-documentation:
.. _Bugfixing-Adding-documentation:
.. _Adding-documentation:

=================
Add Documentation
=================

**Quick links:**

- :ref:`h2document:Formatting-with-reST`
- :ref:`h2document:format-rest-cgl`
- :ref:`h2document:rest-cheat-sheet`
- :ref:`h2document:render-documentation-with-docker`
* :ref:`h2document:Formatting-with-reST`
* :ref:`h2document:format-rest-cgl`
* :ref:`h2document:rest-cheat-sheet`
* :ref:`h2document:render-documentation-with-docker`


The documentation `Changelog <https://docs.typo3.org/typo3cms/extensions/core/latest/>`__
The documentation :doc:`TYPO3 Core Changelog <changelog:Index#typo3-core-changelog>`
and documentation for
`system extensions <https://docs.typo3.org/typo3cms/SystemExtensions/Index.html>`__
is maintained in the core.
:ref:`System Extensions <t3docs:System-Extensions>`
is maintained in the Core.

.. index::
single: Documentation Contribution Workflow; Add Changelog
single: Changelog; Add Entries
.. index::
single: Documentation Contribution Workflow; Add Changelog
single: Changelog; Add Entries

.. _changelog:
.. _changelog:

Changelog
=========

Some patches require a :file:`.rst` (reStructuredText) Changelog file describing the change.
Not all patches
need an entry in the Changelog. Check the list below. Also see the current
`Changelog <https://docs.typo3.org/typo3cms/extensions/core/latest/>`__
:doc:`TYPO3 Core Changelog <changelog:Index#typo3-core-changelog>`
for some examples.

Every file may optionally contain tags, but it must contain at least a
`NotScanned`, `PartiallyScanned` or `FullyScanned` tag for the extension scanner.
See :ref:`t3coreapi:extension-scanner` in TYPO3 Explained for more
information.

.. index::
single: Tools; reST File Generator
single: Changelog; Generate new Entries
single: Documentation Contribution Workflow; Generating reST Files
.. _render-the-changelog:

.. _rest-file-generator:
Render the Changelog locally
----------------------------

If you have `Docker <https://www.docker.com>`__ or `Podman <https://podman.io/>`__
installed you can try out the rendering of the changelog locally:

.. tabs::

.. group-tab:: Docker

.. code-block:: bash
cd typo3/sysext/core
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
.. group-tab:: Podman

.. code-block:: bash
cd typo3/sysext/core
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
.. index::
single: Tools; reST File Generator
single: Changelog; Generate new Entries
single: Documentation Contribution Workflow; Generating reST Files

.. _rest-file-generator:

Forger reST Helper
------------------
Expand Down Expand Up @@ -76,10 +103,10 @@ need to go into :file:`typo3/sysext/core/Documentation/Changelog/<release>/`.

Choose one which fits your patch:

.. index::
single: Documentation Contribution Workflow; Breaking Changes
.. index::
single: Documentation Contribution Workflow; Breaking Changes

.. _documenting-changelog-breaking-changes:
.. _documenting-changelog-breaking-changes:

Breaking Changes
~~~~~~~~~~~~~~~~
Expand All @@ -89,21 +116,21 @@ that may break extensions if they use this part.

**Mandatory sections:**

#. **Description** - why things had to break backwards compatibility.
#. **Description** - why things had to break backwards compatibility.

#. **Impact** - how will the change affect your installation.
#. **Impact** - how will the change affect your installation.

#. **Affected Installations** - describe scenarios under which circumstances
a TYPO3 install will be affected by this change.
#. **Affected Installations** - describe scenarios under which circumstances
a TYPO3 install will be affected by this change.

#. **Migration** - provide instructions what needs to be done to get things
working again. Explicitly mention if no migration is possible.
#. **Migration** - provide instructions what needs to be done to get things
working again. Explicitly mention if no migration is possible.


.. index::
single: Documentation Contribution Workflow; Deprecations
.. index::
single: Documentation Contribution Workflow; Deprecations

.. _documenting-changelog-deprecations:
.. _documenting-changelog-deprecations:

Deprecations
~~~~~~~~~~~~
Expand All @@ -113,21 +140,21 @@ for a planned removal. See more information: :ref:`Deprecations <deprecations>`

**Mandatory sections:**

#. **Description** - why things had to be deprecated.
#. **Description** - why things had to be deprecated.

#. **Impact** - how will the change affect your installation.
#. **Impact** - how will the change affect your installation.

#. **Affected Installations** - describe scenarios under which circumstances
an TYPO3 install will be affected by this change.
#. **Affected Installations** - describe scenarios under which circumstances
a TYPO3 install will be affected by this change.

#. **Migration** - provide instructions what needs to be done to get things
working again. Explicitly mention if no migration is possible.
#. **Migration** - provide instructions what needs to be done to get things
working again. Explicitly mention if no migration is possible.


.. index::
.. index::
single: Documentation Contribution Workflow; Features

.. _documenting-changelog-features:
.. _documenting-changelog-features:

Features
~~~~~~~~
Expand All @@ -136,15 +163,15 @@ A patch adds new functionality.

**Mandatory sections:**

#. **Description** - what can the new feature do.
#. **Description** - what can the new feature do.

#. **Impact** - how users are affected by this new feature.
#. **Impact** - how users are affected by this new feature.


.. index::
.. index::
single: Documentation Contribution Workflow; Important Information

.. _documenting-changelog-important-information:
.. _documenting-changelog-important-information:

Important Information
~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -154,12 +181,12 @@ important enough to require a Changelog entry.

#. **Description** - describe what is so important it needed an rst snippet

.. index::
single: Documentation Contribution Workflow; Checking reST Files
single: Tools; Checking reST Files
single: Changelog; Checking
.. index::
single: Documentation Contribution Workflow; Checking reST Files
single: Tools; Checking reST Files
single: Changelog; Checking

.. _changelog-check-rst:
.. _changelog-check-rst:

Check Your `rst` File
---------------------
Expand All @@ -168,40 +195,27 @@ When your change is finished, you can run the following script to check that
your rst file is ok. The script will check all files in
:file:`typo3/sysext/core/Documentation/Changelog`:

.. code-block:: shell
:caption: shell command
.. code-block:: shell
:caption: shell command
Build/Scripts/validateRstFiles.php
Build/Scripts/validateRstFiles.php
This script will check if the .rst files contain all mandatory tags that
are required for the Changelog. It will **not** do a reST syntax check.

In order to make sure that your file contains no syntax errors and will
be rendered correctly, do one or more of the following:

* Check out :ref:`h2document:format-rest-cgl`.
* Use an editor or IDE that properly supports reST and shows errors
* Render the Changelog locally with docker as explained in the next section

.. index::
single: Documentation Contribution Workflow; Rendering Changelog
single: Tools; Rendering Changelog
single: Changelog; Rendering

.. _render-the-changelog:

Render the Changelog
--------------------

If you wish to render the Changelog locally, you can use docker as described
in :ref:`h2document:render-documentation-with-docker`.

.. important::
* Check out :ref:`h2document:format-rest-cgl`.
* :ref:`Render the Changelog locally <render-the-changelog>` with Docker or
Podman and resolve all warnings.

If you switch branches, you should rebuild everything. You can simply remove the folder
:file:`Documentation-GENERATED-temp/Cache` and all its contents.
.. index::
single: Documentation Contribution Workflow; Rendering Changelog
single: Tools; Rendering Changelog
single: Changelog; Rendering

.. _documentation-main:
.. _documentation-main:

Policy for Changing the Main Documentation
==========================================
Expand All @@ -211,10 +225,10 @@ Once a new TYPO3 release comes out, the main documentation (e.g. :ref:`t3coreapi

The procedure is documented in :ref:`h2document:update-docs`.

.. index::
single: Documentation Contribution Workflow; Documenting System Extensions
.. index::
single: Documentation Contribution Workflow; Documenting System Extensions

.. _documenting-system-extensions:
.. _documenting-system-extensions:

Document System Extensions
==========================
Expand All @@ -241,5 +255,6 @@ locally with docker to test your changes as described in
More Information
================

* See `Documenting Changes <https://docs.typo3.org/typo3cms/extensions/core/latest/Changelog/Howto.html>`__ for more information on the Changelog
* See :ref:`extension-scanner` in TYPO3 Explained
* See :doc:`Documenting Changes <changelog:Changelog/Howto#documenting-changes>`
for more information on the Changelog
* See :ref:`extension-scanner` in TYPO3 Explained
3 changes: 3 additions & 0 deletions Documentation/Quickstart/6-Patch.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,9 @@ Now with this example in mind, we have two modified files that we want to commit
Please ensure to only add files related to your change to the stage,
and discard unrelated files if reasonable.

If your change is a breaking, a feature or deprecation, add a
:ref:`Changelog entry <changelog>`.

4. Commit the files

.. code:: bash
Expand Down

0 comments on commit d357bde

Please sign in to comment.