Discussion: Docs repo development flow

[amber ore]

Hi!

I'd like to learn and think through how we work in the docs repo.

I asked earlier: "How do different branches of home-assistant.io relate to each other?"

Answer I got from Joost:

• current is the main website right now, things we merge into that branch immediately get published on the website.
• next will be merged to rc at the start of beta week, and from rc to current once it’s released
• current is merged into next every so often, Frenck generally does that

@viscid fossil @fallow knoll @lone holly

Question to Franck:
Do current-next syncs ever create conflicts? If no, should we automate? If yes, should we stop asking for contributions to current?

This seems relevant also to ongoing development of purpose-specific triggers - Franck said some docs have been created on next (and implied some on current?)

[viscid fossil]

correct. PRs related to code go on the next branch, so that they can be merged together with the related code PR, in whichever release that is (in the future). Changes that apply to the current documentation go on the current branch. Frenck handles the merging.

[amber ore]

Thanks. So now, would there be an advantage of switching to default to asking for contributions to next, so we eliminate the need for periodic current->next merges, which can free up Frenck? And limiting it to fixes of incorrect information?

[sage iron]

One thing that is not easy for contibutors is when they set up their changes against the wrong branch and then need to start to rebase. That also triggers a big load of unneeded notifications to people that contributed in the past month. Having an automated backport to current if need to publish directly would also solve other things.

[amber ore]

Thanks. For me this is a point in support of asking to contribute to next by default.

Can you tell me some more about the "notifications to people that contributed in the past month"? How does this happen?

[humble wyvern]

This would be due to the next branch containing the commits on top of current so any changes since a release would have those in, pinging everyone who owns those files

I'd be all for making next the default branch

I think the original intention was to make it easier to make edits from the docs links for those less github inclined for small typo edits etc.

The edit links do go to the current branch, so I would guess, if next is made the default, it would trigger the same effect :/

GitHub needs a ?for_branch=current query param so you could send them to edit but force the flow to point to the correct branch

[amber ore]

btw, I found this documented here (PR): https://developers.home-assistant.io/docs/review-process#home-assistant-documentation

[amber ore]

@sage iron @humble wyvern Regardless of next/current, how about a PR that edits multiple files? Think a small style change, but affecting a lot of files. Would all the code owners for each page get pinged?
Is there currently a way of preventing this?

[lone holly]

Unfortunately not, this is how GitHub works, if we want that changed, we need to ask them to change it

[lone holly]

Do current-next syncs ever create conflicts? If no, should we automate? If yes, should we stop asking for contributions to current?
Yes, constantly. The project is moving fast and branches diverge really quickly (massively). A month release cycle is really a stretch in that regard

[lone holly]

I'm not honestly. In the end, contributors that contribute to next, have generally more experience (programmers/developers/coders as is related to upstream PRs in almost all cases), while contributions to current often involve less experienced people.

I rather have experienced folks cleaning up their branches as they know what to do, vs a first-time docs contributors that tries to contribuite that gets stuck in git stuff

[amber ore]

These are good points.
If we only asked for docs contributions to next, there would be less sync cleanup to be done, and would only depend on how long the PR has been open.