Skip to contentSkip to conversation

Changes needing documentation - a new procedure

DISCUSSION Richard Purdie 2 participants 2 messages Sep 2, 2023

lore
Share & tools
lore
#0 lore raw

I've been concerned for a while about the process of adding documentation influencing changes. Our docs are in a separate repo and this does have advantages. They do span multiple areas of the project and in general this does work well for us. It does mean the docs are consistent and have a common style/voice.

Equally, it is hard to ask users to add documentation changes in their commits and this leads to the docs having to play catchup and pushes a lot of work to the docs maintainers.

We're therefore going to try something new where I'll ask people to add notes to a file in OE-Core, DOCS-WIP when they make a change which needs docs updates. This will include changes which need a release notes or migration guide entry. The docs maintainers will then know what needs to be done and hopefully have at least the basic information they need to make the docs changes needed.

This is an experiment but hopefully one that will be successful and let our docs continue to grow.

Cheers,

Richard

#1 lore raw
Quoted 28 lines

-----Original Message-----
From: [email protected] <openembedded- [email protected]> On Behalf Of Richard Purdie
Sent: den 2 september 2023 09:20
To: openembedded-core <[email protected]>; openembedded-architecture <openembedded- [email protected]>
Cc: Michael Opdenacker <[email protected]>
Subject: [Openembedded-architecture] Changes needing documentation - a new procedure

I've been concerned for a while about the process of adding documentation influencing changes. Our docs are in a separate repo and this does have advantages. They do span multiple areas of the project and in general this does work well for us. It does mean the docs are consistent and have a common style/voice.

Equally, it is hard to ask users to add documentation changes in their commits and this leads to the docs having to play catchup and pushes a lot of work to the docs maintainers.

We're therefore going to try something new where I'll ask people to add notes to a file in OE-Core, DOCS-WIP when they make a change which needs docs updates. This will include changes which need a release notes or migration guide entry. The docs maintainers will then know what needs to be done and hopefully have at least the basic information they need to make the docs changes needed.

Quoted 6 lines

This is an experiment but hopefully one that will be successful and let our docs continue to grow.

Cheers,

Richard

I would recommend to make DOCS-WIP a directory where you drop one file per change. That way you avoid all problems with conflicts during testing, integration and cherry-picking. You also automatically get a list of the pending changes by listing the files in that directory.

//Peter