ReleaseNotes/Guidelines

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• 25.2
• 24.8
• 24.2
• 7.6
• 7.5
• 7.4
• 7.3
• 7.2
• 7.1
• 7.0
• 6.4
• 6.3
• 6.2
• 6.1
• 6.0
• 5.4
• 5.3
• 5.2
• 5.1
• 5.0
• 4.4
• 4.3
• 4.2
• 4.1
• 4.0
• 3.6
• 3.5
• 3.4
• 3.3

This page explains how to write and maintain LibreOffice release notes wiki pages.

The purpose of release notes

While release notes are nice for marketing and documenting personal achievements, they have multiple other uses. The documentation team uses them as a reference for changes and additions (hint: the doc team will love you forever, if you write help for features you add instead of leaving them to conduct detective work). Important for QA and development, skimming the notes is sometimes the quickest way to find out when something was implemented or changed. They are also the main reference for when a feature or support for a platform was deprecated and eventually removed.

Creating new release notes page

Go into the history view of the nearest previous release notes page, locate the first revision, start editing it and copy the contents to the new page while adapting the version number references. The arguments for the Template:Aboutthispage template should refer to the previous version.

Translations

Having release notes as translatable content brings additional complexity. Refer to our TDF_Wiki/Multilingual article for a summary of how the wiki translation system works.

Before a release notes page is first marked for translation, it has a note saying when in the release cycle it will be marked. Normally, the first marking is done by an experienced wiki administrator who can do the necessary editorial work efficiently with various helper tools.

A common mistake is manually adding or manipulating the <!--T:123--> markers. They are automatically handled by the translation system every time a page is marked for translation.

The main concerns are keeping the translation units small and minimizing the amount of included wiki markup.

Examples of what to do:

• Do not manually add <!--T:123--> markers.
• Only add new (sub)section headers when strictly necessary.
• Always leave blank empty line(s) around (before/after) section headers.

Each time a page is marked for translation, the results in (all) translated pages might take a few minutes to be seen. When editing translation units (in a translated page), the results (in the translated page) are delayed a few minutes.

In order to reduce mistakes and unnecessary work for editors and translators, it is always recommended to review the resulting (original and translated) pages, for instance before marking for translation, or 10 minutes after editing a translation unit (in the translated page). Mistakes are usually much easier to find by the original editor, greatly reducing the extra load on other editors and on multiple translators.

Content

Anyone can add items to the release notes, not only commit authors themselves.

When adding items, only add new headings sparingly, and consider how the different sections are distinguished from each other.

Keep each item short and to the point, for readability and to make translation easier. If you need to provide more details, you can link to a different page (documentation, blog post, bug report, commit, other wiki page...).

Make use of the templates for keys, menu items and buttons: Template:key, Template:bc, Template:button.

Screenshots

Use gallery elements with mode="packed" and heights="123px". This allows you to add a caption to the screenshot while keeping the page mobile-friendly. The image file name (together with its additional options) should be enclosed in <translate> tags, because translators might want to create localized screenshots.

References to bug reports and core commits

In release notes you will see these types of references (in this order):

(FirstName1A LastName1A, FirstName2A LastName2A; AffiliationA) (FirstName1B LastName1B, FirstName2B LastName2B; AffiliationB) {{tdf|123456}} {{commit|abcdefg123456|8}}

• Each Affiliation (or Organization) is written within its own parentheses.
• Note the semicolon before (each) Affiliation, being the last item within each pair of parentheses.
• Use a comma as separator between multiple Authors from the same Affiliation.
• Avoid the use of other signs or symbols that could be misread (such as hyphen, minus, colon...).
• Avoid unneeded connecting words. For instance, instead of Author1, Author2 and Author3 from Organization, always use the aforementioned comma and semicolon symbols: Author1, Author2, Author3; Affiliation.
• Multiple bugs and/or commits could be referenced, each one using its own respective template, one after the other, separated by a space character.

You can learn about the usage of these templates on their respective pages: Template:tdf, Template:commit.

The author and affiliation should be mentioned first, and the bug report and core commit references last. In some cases, an item could include the author and affiliation, while other references might be mentioned in sub-items.

If references to core commits or bug reports are replaced by a link (to a blog post, for example), place it before the author name so it can be translated along with the description.