search

omgnetwork / omgnetwork.github.io

Developer Portal for OMG Network
https://docs.omg.network/
1 stars 3 forks source link

Docs versioning #40

Closed nicholasmueller closed 4 years ago

nicholasmueller commented 4 years ago

issue 10

So I wana start getting us familiar with the workflow using versioning, since we will have this requirement soon. This allows us to "lock-in" the current state of docs as a version. We get a new versions page that allows us to view old doc versions.

So for workflow, this means changes in new PR previews will only be visible appending /next after the base url. ie. https://deploy-preview-31--omgnetwork-docs-demo.netlify.com/next/welcome.html The url without /next reflects the latest published version. Old versions can be viewed through the links on the versions page. Also applies when working locally, append /next to see your changes.

*this 0.0.1 is just for example, when we go live we can re-version it to be whatever is latest, with a v1.0.0

also see my remark about images with respect to versioning in the readme

Pongch commented 4 years ago

just to be sure my understanding is correct:

  1. all changes that are made needs to prepend /next in url
  2. all old versions will be visible, with urls kept in versions page
  3. npm run will build the site content inside /website/versioned_docs/

And given that netlify will point to the head of master, the production site will contain all the previous versions added in step 3. ?

Pongch commented 4 years ago

I'm wondering if docs that live outside the versioning paradigm like network connections will be an issue ? ie. do we need to update the connections on ALL the previous versions ?

on the note of keeping up previous versions, hypothetically, if we have major release: 1.0.0, 2.0.0, 3.0.0 and there are updates/fixes that goes into only 1.0.0. In which case we must only make documentation updates to only 1.0.0. Would this versioning scheme allows for this kind of changes to be simple to perform?

nicholasmueller commented 4 years ago

hmm maybe easier explain more on how it works..so everytime you make a version, docusaurus basically copies all the markdowns (and only the markdowns), dumps them into a folder named version-0.0.1, version-0.0.2 etc. And theres an array of versions that keeps track of the order...

versions = [
  '0.0.2'
  '0.0.1'
]

so the site will show whatever is on top of that list, from that specific folder, at the normal url... if you want to see contents from a folder thats not on the top, the url becomes /0.0.1/welcome.html, and it will render the markdowns from that folder.

so any new changes in /docs wont be in a version folder unless we tell it to be. this is sort of like the "working copy" version. and you can only render those markdowns by adding the /next url. so these are basically "hidden" unless somebody visits /next of course.

and correct, build include all the versioned folders so they are available to at their respective urls.

I'm wondering if docs that live outside the versioning paradigm like network connections will be an issue ? ie. do we need to update the connections on ALL the previous versions ?

on the note of keeping up previous versions, hypothetically, if we have major release: 1.0.0, 2.0.0, 3.0.0 and there are updates/fixes that goes into only 1.0.0. In which case we must only make documentation updates to only 1.0.0. Would this versioning scheme allows for this kind of changes to be simple to perform?

yes, if we want to make a change to old version 1.0.0, we just need to edit whatever is in that version folder. so for the network connections, if we want to have all versions showing the same connections, we have to update all the old folders. or we move it out of the markdowns... and just add a link to a github hosted readme.. or you can create a react page that should render the same for all versions