ReleaseNotes/Guidelines

    From The Document Foundation Wiki

    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.
    • As a general rule, leave blank empty line(s) around (before/after) each new item (of a list).
      • This will generate a new (individual) translation unit for each list's item.
      • Wiki editors that have extensive experience with <translate> tags could be tempted to manually set up relevant <translate> tags in order to obtain individual translation units for each item without the need for blank empty lines. This affects every single translation (in all languages), so please be really sure of what you are doing beforehand.
      • Blank empty lines in-between individual list's items could be manually eliminated after each/the relevant item has been marked for translation first/once, while also editing its relevant <translate> tags appropriately.
        • For most cases, eliminating these blank empty lines is optional, but when it is done, the corresponding <translate> tags must be moved (but not eliminated) to their appropriate place. This should only be performed by an experienced editor. Inadequate editions will greatly negatively impact every single translation (in all languages).
      • This is also valid for ordered (aka numbered) lists (which are infrequent in our release notes pages). This affects the resulting numbering.
        • If adequate <translate> tags have not been manually inserted for each individual item, and blank empty lines have been used in-between items of an ordered list before marking for translation, you can eliminate blank empty lines only after the relevant item has been marked for translation first/once, while taking care of relevant <translate> tags.
        • For ordered (aka numbered) lists, if blank empty lines are not inserted in-between items (so as to obtain the desired numbering), then manually inserting adequate <translate> tags for each individual item is recommended. This should only be performed by editors that have wide experience with <translate> tags. Inadequate editions will greatly negatively impact every single translation (in all languages).

    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.

    They should not be included within <translate> tags.

    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.