Creating / branching a new version


(Robert) #1

Our current version of our API is 3.8.4.

We’re getting ready to release 3.8.7. How should I do that?

I have a new swagger.json so my thought was to start by duplicating the existing project, but I can’t see how / where to do that.


(Erik Hansen) #2

You can use Stoplight versioning within the same project https://docs.stoplight.io/platform/versioning/versions
When you “release” more than one version, you published hub will have a version selector at the top of the page where you can select which version of the hub is shown.

However, since you are only incrementing the PATCH version (https://semver.org/) you may want to only have the latest version of docs “released” since you should not have made any breaking changes in your API.


(Robert) #3

Is it possible to create an alias so striim384.docs.stoplight.io points to striim.docs.stoplight.io?

We need both versions since customers running 3.8.4-3.8.6 won’t have back-end support for the 3.8.7 API.


(Taylor Barnett) #4

Alternative idea:

You create a seperate OAS file for 3.8.7 and link it in the header. (And also have a clear link for the older version too.) I know it is less than ideal since our versioning doesn’t have patch versions, but this way it can still be in all one documentation URL.


(Robert) #5

Is it possible to just copy the existing project?


(Taylor Barnett) #6

Just to clarify, so that it would be different Hub files?

In the way, I suggested, I am imagining them in the same Hub file.


(Robert) #7

Different. The most efficient thing for me at this point would be to copy the existing project and replace the JSON.


(Taylor Barnett) #8

Could you do that if you copy the OAS file and make a new one for the different version in the same project and Hub file?


(Taylor Barnett) #9

I can build a quick example of what I am thinking if you want me to.


(Robert) #10

What would the URL be?

And we need to hide the beta version until 3.8.7 ships.


(Taylor Barnett) #11

Just built an example: https://robert-example.docs.stoplight.io/

You see the two API references I created as header links. They are separate OAS files in one project. You can remove the link to 3.8.7 until it ships.


(Taylor Barnett) #12

Hey @robert! Just wanted to check in on if this would work for you.


(Robert) #13

I’ve been in release mode, updating the API is next on the list after we ship.


(Taylor Barnett) #14

Sounds good! I’ll leave the example up then.