Push doc on merge to master

[zvirja]

The issue is based on the discussion in #559.

@zvirja

should we probably modify CI so that doc is published automatically on push to master? This way if we don't want doc to be released right now - just keep it in a branch. Otherwise, we have this non-synchronized docs and manual work.. 😟

@dtchepak

I'm not sure what to do about publishing docs. It would be nice to auto-publish, but we'll need to look into potentially hiding (draft tag?) some info for when we are documenting unreleased features.

I don't think the non-synchronised docs have been a big problem yet. But avoiding manual work I am generally more than happy to support 😂

@zvirja

It would be nice to auto-publish, but we'll need to look into potentially hiding (draft tag?) some info for when we are documenting unreleased features.

Can't we just don't put it to master then and keep in branch like v5-documentation or vNext-doc? Of course, it would require some merging if you modify original doc in the meanwhile, but it shouldn't happy often.

@dtchepak

I think also should make sure docs branches continue to be checked against latest code.

[zvirja]

@dtchepak I see your point. But let's think about possible scenarios when it might matter:

• Scenario 1. Added new feature to master. Documented it in branch with samples. Later modified the feature, so that doc sample is no longer valid. You can merge change, as master doesn't contain doc sample yet. Comment: We shouldn't rely on doc tests to verify the feature functionality. Therefore, feature could become broken only due to poor coverage, which is another story. If the issue happened because doc sample was fragile - nothing bad happened, as the doc branch hasn't been published yet and we'll capture that anyway on doc merge.
• Scenario 2. Doc branch already exists. Added new feature and want to document it. Doc test fails because branch doesn't contain recent changes from master. Comment: Can be easily solved by a merge from master or by rebase on top of master.

I tried to think about other scenarios were it might matter, but it was hard to spot those. I presume that if we document the existing functionality, those docs are published immediately.

Do you see particular situations when delayed vNext-doc branch might cause issues?

[dtchepak]

@zvirja Might be easiest just to give it a try. If we run into any trouble we can adjust or revert back to the previous approach.