Skip to contentSkip to conversation

Add DOCS-WIP

PATCH Richard Purdie 2 participants 3 messages Sep 5, 2023 1 message not in the archive

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): [email protected]

#1 lore raw
Quoted 19 lines · Richard Purdie via lists.openembedded.org

We've needed a way to queue/note/sync docs changes with our manuals, migration guides and release notes. Add a file which we can use to "stage" information. We can then ask users submitting changes which need docs changes to add information here. This will then make it easier for the docs to be brought into sync as we'll have a much better idea of when something merged and what changes are needed.

---
 DOCS-WIP | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 DOCS-WIP
DOCS-WIP new file +0 -0
new file mode 100644
index 00000000000..0e2baf9e0bf

DOCS-WIP line 4

Quoted 4 lines
DOCS-WIP new file +4 -0
@@ -0,0 +1,4 @@
+This file is intended to note docs changes that are being made by commits so
+that people working on the documentation know that changes are needed. This
+includes entries that would make sense for the migration guide or release notes.
+

This has proven contentious. Whilst I think it would help our docs maintenance, there are differing views:

* it should be a directory for conflict reasons
* we don't want a top level directory for this
* we don't want a directory called "WIP" as it looks bad
* we shouldn't have "partial" half way staging, either the docs are in repo or they're not

I'm weary, I can't reconcile the views being expressed, some people haven't clearly haven't read or understood the proposal reasoning and its turning into a perfect bike shedding exercise.

Much as I think it would be the right direction, some people won't be happy, the complaints are going to annoy me and I'm going to abandon the patch.

Richard

#2 lore raw
Quoted 9 lines · Richard Purdie

This has proven contentious. Whilst I think it would help our docs maintenance, there are differing views:

* it should be a directory for conflict reasons
* we don't want a top level directory for this
* we don't want a directory called "WIP" as it looks bad
* we shouldn't have "partial" half way staging, either the docs are in repo or they're not

Quoted 7 lines

I'm weary, I can't reconcile the views being expressed, some people haven't clearly haven't read or understood the proposal reasoning and its turning into a perfect bike shedding exercise.

Much as I think it would be the right direction, some people won't be happy, the complaints are going to annoy me and I'm going to abandon the patch.

Ugh, this is *not* the outcome I was expecting. Whoever is bike
shedding: shame on you.

My two eurocents:
1. Top level directory is fine.
2. Top level directory called 'WIP' is fine, if it's not in a release or a stable branch.
3. I'm regularly adding features or changing behavior that require doc updates. I'm just as regularly forgetting to document what I'm doing, and this would've helped. The most notorious example is per image license checks which went undocumented for several years.

I'm going to resurrect this with the upcoming Y2038 fixes, or oe-setup-build rewrite that I just did, but holding off due to feature freeze.

Alex

#3 lore raw
Quoted 19 lines · Alexander Kanavin
Quoted 9 lines · Richard Purdie

This has proven contentious. Whilst I think it would help our docs maintenance, there are differing views:

* it should be a directory for conflict reasons
* we don't want a top level directory for this
* we don't want a directory called "WIP" as it looks bad
* we shouldn't have "partial" half way staging, either the docs are in repo or they're not

Quoted 7 lines

I'm weary, I can't reconcile the views being expressed, some people haven't clearly haven't read or understood the proposal reasoning and its turning into a perfect bike shedding exercise.

Much as I think it would be the right direction, some people won't be happy, the complaints are going to annoy me and I'm going to abandon the patch.

Quoted 7 lines

Ugh, this is *not* the outcome I was expecting. Whoever is bike
shedding: shame on you.

My two eurocents:
1. Top level directory is fine.
2. Top level directory called 'WIP' is fine, if it's not in a release or a stable branch.

Well, some of the views are mine, some of them are not, I just tried to summarise for the archives. I am definitely against a WIP directory, the optics on that look terrible as it is too open to misinterpretation. There is no guarantee it would not make a release.

Whilst I understand the technical merit of a directory, I really don't want a directory at all, the idea was to keep it really simple and it was working on the assumption that things would not be long in the file so merge conflicts would be minimal. With a clever choice of section separator, I think diff could be fooled into doing a decent job since we don't care about ordering.

The bike shedding was going to quickly go in the direction of "we could have multiple directories, one for release note annotations, one for migration guide and one for docs changes, we could then have a script which did X and Y and magic and ... like python or ZZZ does" and this is partly why I'm just giving up, lots of excitement about complicated things which nobody has time to implement/maintain. Case in point, how many people have helped improve the docs build automation since it was created? The code mostly works but is horrible, it could be so much nicer.

Given the direction things were looking to go, I don't have the time/energy to discuss/argue this any further.

To be honest I'm struggling with things in general. Problematic patches come in and I end up arguing about them on my own even if I know that were they to merge I'd get a load of "why did you let X in when it causes Y performance to degrade or complicates Z". There is far to much reliance that I'll block things and therefore nobody else has to make the effort :/.

Quoted 4 lines

3. I'm regularly adding features or changing behavior that require doc updates. I'm just as regularly forgetting to document what I'm doing, and this would've helped. The most notorious example is per image license checks which went undocumented for several years.

You're not alone, 2/2 was an example of my own making I was trying to head off issues with.

Cheers,

Richard