Skip to content

/ NSubstitute

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Push doc on merge to master #561

Open
zvirja opened this issue May 9, 2019 · 2 comments
Open

Push doc on merge to master #561

zvirja opened this issue May 9, 2019 · 2 comments
Labels
build documentation good first issue help wanted

Comments

@zvirja
Copy link
Contributor

@zvirja zvirja commented May 9, 2019

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
Copy link
Contributor Author

@zvirja zvirja commented May 9, 2019

@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
Copy link
Member

@dtchepak dtchepak commented May 9, 2019

@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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
build documentation good first issue help wanted
Projects
None yet
Milestone
No milestone
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
@dtchepak @zvirja @alexandrnikitin
You can’t perform that action at this time.