[5pt] Describe English style to use in release notes

[Totktonada]

Epic: Release notes

Describe English style to use in release notes

Product: Tarantool (mostly about tarantool, but I guess it is applicable for all products)
Since: N/A
Audience/target: Tarantool developers and documentarians
Root document: Somewhere around our documentation guides
SME: @ NickVolynkin, @ Gerold103, @ patiencedaur

Details

See also: #1285

The discussion was started here. I'll cite:

@Gerold103:

You might notice that we use imperative in all changelog records. Would be good to be consistent.

@Totktonada:

In the past release notes:

• Imperative mood is used when we start to do X: say, 'Deploy packages for Fedora 32 ( replication.reconnect_timeout option #4966)'.
• Past tense is used to describe a past (changed / fixed) behaviour: say, 'Fixed a false positive panic when yielding in debug hook (gh-5649)'.
• Present tense is used to describe a new behaviour: say, 'Data changes in read-only mode are now forbidden (gh-5231)'.

Unlike using an imperative mood, this approach results in a text that is 'written for a human', like an article about changes. For me, it looks good.

However, I'm not an expert neither in grammar, nor in documentation writting, so it is better to ask @tarantool/doc team.

You might notice that we use imperative in all changelog records. Would be good to be consistent.

There is no consistency in current unreleased changelog entries, but I hope we'll proof-read them before a next release and adjust to a certain style. We can elaborate some preliminary agreements with the documentation team here.

To be honest, I really don't spin around grammatic rules enough to insist on my vision. However it looks meaningful for me and if we'll agree on another set of rules, I would like to know a reasoning behind.

Definition of done

• There is a page with recommendations how to write grammatically correct release notes.
• @Totktonada understands how to write changelog entries.

Tentative directions

• Make a list of the most common problems documentarians and translators face with RNs. See [8pt] Improve release notes: workflow and user experience #1285
• Analyze the corresponding sections (if they exist) in Microsoft and Google style guides
• Read the article provided as a guideline in [8pt] Improve release notes: workflow and user experience #1285
• Outline the contents
• Start writing :)

---

]Notes from @ lenkis:

Problems with OS Tarantool release notes (RN):

1. No style guide for RN, so writers need to brush up the draft a lot (e.g. RN items are phrased differently).
   TODO: Introduce a simple style guide for all RN contributors.

2. No automatic integration of RN into the manual, so writers need to do it manually.
   TODO: If we continue mirroring RN in the manual, automate md-to-rst import.

3. Too wordy RN section in the manual, which adds no value beyond RN text at GH.
   TODO: Think of making the most of RN as a community communication tool. Here is an article for inspiration: https://uxdesign.cc/the-art-of-writing-great-release-notes-6607e22efae1

---

Draft Notion document with ideas: https://www.notion.so/tarantool/WIP-Release-notes-workflow-b4292dbf8fbd41d58a1983546de4a879

[patiencedaur]

I agree with @Totktonada's linguistic suggestions in the description.

I have several more questions/comments about the process:

Q: Who launches gen-release-notes and at what exact point in time?
A: @ kyukhin does right before the release. The commit with the release notes is tagged with the release tag.

Q: Let's add links to gh-issues in the release notes, convert it to rst, and put it in the right place automatically!
A: No, this is not a frequent task. Run pandoc and sed (see below), then put the artifact in the right place manually.

Q: gen-release-notes generates CE notes. What's about EE and TDG?
A:
TDG: https://github.com/tarantool/tdg2/blob/master/CHANGELOG.md is updated sporadically. Probably apply actions 1–2 and 6–8 below.
EE: there is the old EE, the new EE, and the SDK, which can be built on top of both the old and new EE using cmake.
See more in Notion.

Q: What pages change with every new release (and version)?
A:
CE: https://www.tarantool.io/en/doc/latest/release/ and everything lower-level. Related issue: #2571.
EE: none (with the current structure of enterprise_doc as of January 31, 2022)
TDG: https://www.tarantool.io/en/tdg/latest/release/ and everything lower-level.

Q: What's the best place for the RN style guide?
A: https://www.tarantool.io/en/doc/latest/contributing/docs/

[NickVolynkin]

pandoc -f md -t rst -o changelog.rst changelog.md
sed -i 's,gh-(\d*),:tarantool-issue:`$1`,g' changelog.rst

как-то так

[patiencedaur]

1. разработчики пишут индивидуальные changelogs и складывают их в tarantool/changelogs/unreleased
2. документаторы вычитывают эти файлы
   -- пункты 1 и 2 делаются постоянно раз в 2 недели --
3. Кирилл с помощью gen-release-notes генерирует release notes для Tarantool CE и ставит тег. файл лежит в tarantool/changelogs
   -- релиз появился на гитхабе --
4. документаторы приходят в папку и вручную оттуда забирают этот файл.
5. выполняют команды выше
6. вручную кладут файл в корень страницы https://www.tarantool.io/en/doc/latest/release/
7. добавляют на страницы ниже по уровню информацию о новом релизе
   -- прошло не более 5 дней после релиза --
8. добавляются перекрёстные ссылки
   (здесь идёт маркетинг)

Чем полнее документация, тем лучше, но сколько успеем к маркетинговой кампании

В ЕЕ, скорее всего, будет что-то похожее (повторить все действия). SME: @ locker
Для TDG повторять шаги 4-8 для готового файла (когда и кто его создаёт?). SME: Саша Митичев

[patiencedaur]

Document not only the verb form, but also formatting rules for cases like the following:

[2.4.0] - 2022-01-28
- disable autocomplete in the role editing form.
- clear the error message in the delete tenant modal.
...

what does a release title look like?
date format
parentheses and dash
ending punctuation
capitalization

[patiencedaur]

@ locker is adding to EE a script similar to gen-release-notes in CE:
https://github.com/tarantool/tarantool-ee/issues/14