Skeleton new push docs

[KevinMind]

Relates to: #15030

First commit is to align on the change in the structure, before I fill in the details of the open documents. lmk what you think.

Description

• Re-organize push docs to be more scalable as new information needs to be added/modified
• Update push docs according to changes in the push flow.

Context

The current push doc was long, somewhat outdated, and (for me at least) a bit difficult to follow, especially making edits.

This is why I split the docs into a main "push-duty.rst" doc that outlines the high level process of what should happen before/during/after a push and then link to relevant sub documents that explain in more detail an isolated step in the flow e.g. "tagging a service", "drafting a release doc".

Testing

Follow the readme to make docs locally to view the updated docs.

[KevinMind]

Each link in the push-duty.rst would link to the document or a specific section to execute the specific task. I think I can add some additional details in push-duty.rst itself as well but again, would like 👍 on the overall structure before committing more effort.

[willdurand]

It'd be easier to follow if this was split into two patches. One that updates the structure of the current page, and a second one with the changes for the new way of doing pushes.

[KevinMind]

It'd be easier to follow if this was split into two patches. One that updates the structure of the current page, and a second one with the changes for the new way of doing pushes.

@willdurand So, essentially, keep the existing push-duty.rst in this patch? And only remove after the content is updated in the new files? Do I get it? Happy to do it that way, just didn't see any particular benefit since the existing file is already incorrect.

[diox]

I agree with Will: the problem is right now it's kinda difficult to see what changed since the split and the changes are mixed together.

[KevinMind]

@willdurand @diox wdyt? Is this better for reviewing?

[KevinMind]

@willdurand @diox any blockers merging this still?

[diox]

Not quite sure where this is going.

When we asked for the changes to be separated into 2 patches I was thinking you'd have one patch to split the existing docs, then another to update it with new reworded content. That way we could easily check nothing is missing from each step.

Here you have kept the old docs but the new split docs you're introducing are completely reworded and incomplete content so I'm not sure this is mergeable. But I am OK with the split structure idea.

[KevinMind]

Not quite sure where this is going.

When we asked for the changes to be separated into 2 patches I was thinking you'd have one patch to split the existing docs, then another to update it with new reworded content. That way we could easily check nothing is missing from each step.

Here you have kept the old docs but the new split docs you're introducing are completely reworded and incomplete content so I'm not sure this is mergeable. But I am OK with the split structure idea.

I don't really want to spend time trying to force the existing docs into the structure I have here. I would rather just use them as inspiration. That's why I deleted them.

The idea would be to merge this. and open separate smaller PRs updating the content sections. That way it can be done more continuously. I have opened doc update PRs before that ran into the issue of being to large so I'm trying this approach, thinking it will be faster.

The downside is that the docs are "incomplete" for a time. I don't think that is really a problem. wdyt?

[diox]

My biggest worry is losing info in the process.

At the moment for instance the new version is missing the section about handling deps or security fixes. It would have been more obvious if you executed the split by not changing any content and just moved those sections around (either all in a single PR or one by one), then focused on making changes in content after.

[KevinMind]

I think you might be overthinking this. At every step, if I add content into the new docs I will be "moving" it from the old. So you will see a small number of "red" lines on the old docs and a slightly larger number of "green" lines.

Each PR will be small and focused. I don't think it will be an issue and trying to force the existing content into the new structure will either be a lot of wasted effort or end up with a monster PR, what I'm explicitly trying to avoid.

We've wasted several days on this already. I would like to get started on actual content creation. Can we disagree and commit? Or would you be willing to help with creating these docs?