Decide how to document unreleased features
Closed this issue · 10 comments
This was already discussed here, but now I am opening a proper issue
Problem
When some features go in the VSpaceCode or Which Key master branch, they are not released until a tag is created.
Instead this website is built on each commit.
We don't want to put in the website documentation for features that are not yet released.
Possible solutions
This are the solutions that come to my mind:
Develop branch
Commits on this repositories will be done on the develop branch.
The website reflects the master branch, so we could merge the develop branch with the master branch when VSpaceCode and Which Key are released.
Cons:
- confusing for new contributors
Store documentation on the VSpaceCode and Which Key repositories
Documentation for the project will be stored in the project themselves (maybe in a docs/ dir or something like this).
So, on each tag on VSpaceCode and Which Key repositories, the docs for those projects are updated in some way.
I don't know if this is feasible, we should check how to do it.
Pros:
- we could release documentation for VSpaceCode and Which Key independently.
Rebuild the website only on tag
Similar to the approach of the VSpaceCode and Which Key repositories, we could trigger the github action that builds this website only on tags.
steven commented on this here, by saying:
That might still be problematic because two repos maintain two versions. But some sort of develop/master or release/next separation would still be nice.
Could you elaborate on that? I haven't fully understood your point.
versioning with docusaurus
Develop branch
Develop branch also has the con of not able to manage two different release cycle for each project. For example, if there is some doc changes for both which-key and VSpaceCode in the develop branch and we want to release a new website only one of the projects, it can be difficult to merge.
One simpler fix to this is to have two branches, vspacecode-next and which-key-next that contain the doc for the upcoming changes respectively.
Rebuild the website only on tag
If we are maintaining tags in this repo, would the tag number follow the release cycle of VSpaceCode of which-key? This is the same problem with the develop branch above.
versioning with docusaurus
I think this can only version the whole website as well
Store documentation on the VSpaceCode and Which Key repositories
This should let us version the doc as part of the repo; however, we need some engineering to make this work. FYI, keybindings.md is currently deployed directly from VSpaceCode so it is possible to do a cross repo automated commit.
I got your point on tags now, thanks.
FYI, keybindings.md is currently deployed directly from VSpaceCode so it is possible to do a cross repo automated commit.
Right! So yeah, I think that this is the best solution, because it doesn't require manual intervention at all and because the documentation can be updated in the same PR of the feature.
I agree that would be nice, but there is some engineering cost to figure that out for sure like how to manage the sidebar link.
I propose that we use the two develop branch approach I described earlier meanwhile to mange the upcoming doc changes.
ok for me.
there is some engineering cost to figure that out for sure like how to manage the sidebar link.
Manually? 😅 I can't see a simpler solution right now. Most of the times you will just edit current pages, so I don't see a big problem about it.
Also assets, should the assets be in this repo or distributed? Anyway, let's try the develop branch approach for now and see how that goes since it is a simpler model to implement and use.
I documented the process here
If we create these branches this issue can be closed, right?
That's awesome~!!!! Thanks, let's close this :)
vspacecode-develop branch should be renamed to vspacecode-next
Ah right! Done :)