Task #89330

Allow linking to changelog entries from documentation

Added by Tymoteusz Motylewski over 1 year ago. Updated 8 months ago.

Status:
Closed
Priority:
Should have
Assignee:
-
Category:
Documentation
Target version:
-
Start date:
2019-10-02
Due date:
% Done:

0%

Estimated time:
TYPO3 Version:
10
PHP Version:
Tags:
Complexity:
Sprint Focus:

Description

Currently it is not possible to link from documentation (e.g. TYPO3 Explained) to changelog entries.

The documentation team proposed a solution which requires every changelog entry to define a linking target:

.. include:: ../../Includes.txt

.. _Feature-84545-Allow-temporary-files-to-be-stored-outside-the-document-root:

==============================================================================
Feature: #84545 - Allow temporary files to be stored outside the document root
==============================================================================

See :issue:`84545`

THEN
you could link like so:

:ref:`t3changes:Feature-84545-Allow-temporary-files-to-be-stored-outside-the-document-root`

And in the Settings.cfg we would need a mapping of 't3changes' to the url.

TODO:
- add automatic linking target to forger rst generator
- optionally add linking targets to existing rst's
- add 't3changes' to Settings.cfg of manuals

In the longer run we should include knowledge described in the changelog entries into main documentation (TYPO3 explained/references...), so the question is whether it makes sense to encourage linking to changelog.

#1

Updated by Tymoteusz Motylewski over 1 year ago

  • Description updated (diff)
#3

Updated by Christian Eßl over 1 year ago

  • Category set to Documentation
#4

Updated by Sybille Peters 8 months ago

  • Status changed from New to Closed

I think this is now sufficiently handled, see https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/GeneralConventions/CodingGuidelines.html#link-to-changelog

This is handled, not with :ref: (which would require a header label in the changelog), but with :doc: which requires that you use the path, e.g.

:doc:`t3core:Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions`

This does have the possible downside, that the link will be broken if the filename changes. This does happen sometimes, but usually not after the Changelog has been moved from master to its final location.

Linking to the changelog as described, requires that t3core is added to Settings.cfg (which has already been done in "TYPO3 EXplained" etc.).

t3core = https://docs.typo3.org/c/typo3/cms-core/master/en-us/

Closing now.

Also available in: Atom PDF